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DNOS Software Manuals 

This diagram shows the manuals supporting DNOS, arranged according to user type. Refer to the block identified by your user 
group and all blocks above that set to determine which manuals are most beneficial to your needs. 


All DNOS Users: 


DNOS Concepts and Facilities 
2270501-9701 


DNOS Operations Guide 
2270502-9701 


DNOS System Command 
Interpreter (SCI) Reference Manual 
2270503-9701 

DNOS Text Editor 
Reference Manual 
2270504-9701 


DNOS Messages and 
Codes Reference Manual 
2270506-9701 

DNOS Reference Handbook 
2270505-9701 


DNOS Master Index to 
Operating System Manuals 
2270500-9701 



High-Level 
Language Users: 

COBOL Reference Manual 
2270518-9701 

DNOS COBOL 
Programmer’s Guide 
2270516-9701 
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Package Documentation 
2272109-9701 
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2270519-9701 
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Programmer’s Guide 
2270517-9701 

FORTRAN-78 Reference 

Manual 

2268681-9701 

DNOS FORTRAN-78 
Programmer’s Guide 
2268680-9701 

MATHSTAT-78 
Programmer’s Reference 
Manual 
2268687-9701 

FORTRAN-78 ISA 
Extensions Manual 
2268696-9701 

Tl BASIC Reference Manual 
2308769-9701 

RPG II Programmer’s 

Guide 

939524-9701 
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Language Users: 

990/99000 Assembly 
Language Reference 
Manual 
2270509-9701 
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Programmer’s Guide 
2270508-9701 

DNOS Link Editor 
Reference Manual 
2270522-9701 

DNOS Supervisor Call 
(SVC) Reference 
Manual 
2270507-9701 


Security 

Managers: 

DNOS Security 
Manager’s Guide 
2308954-9701 
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Productivity 
Tools Users: 

DNOS Sort/Merge 
User’s Guide 
2272060-9701 

TIFORM 

Reference Manual 
2234391-9701 

DNOS Query-990 
User’s Guide 
2276554-9701 

DNOS Data Base 
Management System 
Programmer’s Guide 
2272058-9701 

DNOS Data Base 
Administrator User’s 
Guide 

2272059-9701 

Data Dictionary 
User’s Guide 
2276582-9701 

DNOS TIPE 
Reference Manual Kit 
2308868-0001 

DNOS TIPE 
Exercise Guide Kit 
2308869-0001 

DNOS COBOL Program 
Generator User’s Guide 
2234375-9701 
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Communications 
Software Users: 

DNOS DNCS/SNA 
User’s Guide 
2302663-9701 

DNOSDNCS 
Operations Guide 
2302662-9701 

DNOSDNCS914A 
User’s Guide 
2302664-9701 

DNOS 3270 Interactive 
Communications Software 
(ICS) User’s Guide 
2302670-9701 

DNOS 3780/2780 
Emulator User’s Guide 
2270520-9701 

DNOSDNCS System 
Generation Reference 
Manual 
2302648-9701 

DNOSDNCS X.25 
Remote File Transfer 
(RFT) User’s Guide 
2302640-9701 

DNOS Remote Terminal 
Subsystem (RTS) 

User’s Guide 
2302676-9701 

DNOS Distributed Network 
l/O(DNI0) User’s Guide 
2308793-9701 

DNOS Common 
Communications Utilities 
2308783-9701 



Systems 

Programmers: 

DNOS System Generation 
Reference Manual 
2270511-9701 

DNOS Systems 
Programmer’s Guide 
2270510-9701 

ROM Loader User’s Guide 
2270534-9701 



Source 
Code Users: 

DNOS System 
Design Document 
2270512-9701 

DNOS SCI and Utilities 
Design Document 
2270513-9701 









DNOS Software Manuals Summary 


Concepts and Facilities 

Presents an overview of DNOS with topics grouped by operating system functions. All new users (or 
evaluators) of DNOS should read this manual. 

DNOS Operations Guide 

Explains fundamental operations for a DNOS system. Includes detailed instructions on how to use each 
device supported by DNOS. 

System Command Interpreter (SCI) Reference Manual 

Describes how to use SCI in both interactive and batch jobs. Describes command procedures and gives 
a detailed presentation of all SCI commands in alphabetical order for easy reference. 

Text Editor Reference Manual 

Explains how to use the Text Editor on DNOS and describes each of the editing commands. 

Messages and Codes Reference Manual 

Lists the error messages, informative messages, and error codes reported by DNOS. 

DNOS Reference Handbook 

Provides a summary of commonly used information for quick reference. 

Master Index to Operating System Manuals 

Contains a composite index to topics in the DNOS operating system manuals. 

Programmer’s Guides and Reference Manuals for Languages 

Contain information about the languages supported by DNOS. Each programmer’s guide covers oper- 
ating system information relevant to the use of that language on DNOS. Each reference manual covers 
details of the language itself, including language syntax and programming considerations. 

Performance Package Documentation 

Describes the enhanced capabilities that the DNOS Performance Package provides on the Model 99D/12 
Computer and Business System 800. 

Link Editor Reference Manual 

I Describes how to use the Link Editor on DNOS to combine separately generated object modules to 
form a single linked output. 

Supervisor Call (SVC) Reference Manual 

Presents detailed information about each DNOS supervisor call and DNOS services. 

DNOS System Generation Reference Manual 

Explains how to generate a DNOS system for your particular configuration and environment. 

User’s Guides for Productivity Tools 

Describe the features, functions, and use of each productivity tool supported by DNOS. 

User’s Guides for Communications Software 

Describe the features, functions, and use of the communications software available for execution 
under DNOS. 

Systems Programmer’s Guide 

Discusses the DNOS subsystems and how to modify the system for specific application environments. 

ROM Loader User’s Guide 

Explains how to load the operating system using the ROM loader and describes the error conditions. 

DNOS Design Documents 

Contain design information about the DNOS system, SCI, and the utilities. 

DNOS Security Manager’s Guide 

Describes the file access security features available with DNOS. 
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Preface 


This manual discusses the functional characteristics of the Texas Instruments Distributed 
Network Operating System (DNOS) and is intended for the systems programmer. It provides 
information required for modifying the DNOS system to meet the specific needs of an 
applications environment. Directed to object-level implementation, this manual is not a detailed 
guide for the user who has access to source code. 

This manual contains the following sections and appendixes: 

Section 

1 DNOS System Overview — Discusses the structure, flow, and loading of the system and 
the distinctive DNOS subsystems. The subsystems described are job management, 
segment management, name management, and interprocess communication (IPO). 

2 Disk and File Organization — Describes the files that DNOS supports and the disk 
structures that support the files. 

3 Extending SCI — Describes the System Command Interpreter (SCI), the use of SCI 
primitives, and the procedure for adding commands to support a specific applications 
environment. 

4 Writing an SVC Processor — Explains the procedure for writing supervisor call (SVC) 
processors for applications-oriented SVCs and for including these processors in a 
custom-generated system. 

5 Writing a DSR — Describes the input/output (I/O) system and how to write a device 
service routine (DSR). This section also describes the interrupt types and the DSR 
support routines. 

6 DNOS Accounting System — Discusses the capabilities and use of the accounting 
system. 

7 File Security — Explains what a programmer needs to know about a system that 
supports file security. 

8 Analyzing System Problems — Describes system crashes that occur during system 
loading and after the system begins executing. This section discusses both the system 
crash dump and utility XANAL, which lists the data in the dump. It also explains how to 
force a system crash. 
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Section 

9 Adding Error Messages — Discusses error processing and explains how to add error 
messages required for user-supplied system programs. 

10 International Considerations — Explains the method and results of changing the 
country code of the system and how to customize DNOS for a particular country. 

11 Differences Between DX10 and DNOS — Describes the differences between DX10 and 
DNOS as they relate to migration of DX10 to DNOS. 

12 Special Features of DNOS — Describes some special features of DNOS and how they 
are used. 

The DNOS software manuals shown on the support manual diagram (frontispiece) contain related 
information. The ROM Loader User’s Guide (part number 2270534-9701) contains information 
about how to load DNOS from devices accessible on the TILINE* peripheral bus and on the 
communications register unit (CRU). 




* TILINE is a registered trademark of Texas instruments Incorporated. 
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DNOS System Overview 


1.1 DNOS SYSTEM STRUCTURE 

The Texas Instruments Distributed Network Operating System (DNOS) is a general-purpose oper- 
ating system for the Texas Instruments Business Systems and Model 990 Computers. It allocates 
system resources to the jobs executing on the computer system to provide maximum perfor- 
mance based on information suppiied by the user and on real-time performance analysis. In the 
DNOS environment, a job is a set of one or more cooperating programs (tasks) and performs one 
or more functions. 

DNOS has two parts; one is memory resident and the other is disk resident. The memory-resident 
portion, called the kernel, is loaded into memory during the initial program load (IPL). (The 
memory-resident parts of the system are linked together when the operating system is generated.) 
The kernel must reside in main memory before any processing can occur. 

The kernel provides support for activating and terminating tasks and for processing supervisor 
calls (SVCs) and interrupts. It also provides support for system tasks in the form of common 
^ routines and functions callable from system tasks. 

Disk-resident modules of the system are brought into main memory from disk storage as they are 
needed to perform specific functions. This disk-resident part of DNOS consists of various system 
tasks that perform primarily queue-serving functions. 

Figure 1-1 shows a physical layout of DNOS. In the figure and elsewhere In this manual, the right 
angle bracket (>) preceding a value indicates a hexadecimal value. 

The kernel includes the following parts: 

Transfer Vectors 

A transfer vector is a pair of consecutive memory words. The first word contains the address 
of a 16-word workspace register area. The second word contains the address of a subroutine 
entry point. A transfer vector is used to perform a type of control transfer called a context 
switch. An example of a transfer control switch is the transfer of control to an interrupt sub- 
routine when an interrupt occurs. Business Systems and Model 990 Computers support 16 
transfer vectors for interrupts. They also support 16 transfer vectors for extended operations 
(XOPs). XOPs perform system-defined functions implemented by software. 

Nucleus 

The nucleus contains routines that support queuing, synchronization, linking to other rou- 
tines, and managing the scheduler. The nucleus portion also includes the system table area. 


0^ 
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Figure 1-1. Physical Layout of DNOS 
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System Tables 

All the data structures needed to support system operations are located in the table areas. 
These areas include segment management table areas, file management table areas, the 
system job communication area, and the partial bit map for the system disk. 

System Components 

System components include the scheduler, Supervisor Call (SVC) processors, and the device 
service routines (DSRs). You use these components temporarily, as segments mapped into 
the logical memory space as required. 

In addition to the kernel, DNOS memory space also contains the following: 

System Tasks 

The memory-resident system tasks are loaded into memory next to the system segments. 
The memory-resident tasks include file management, disk management, and the task loader. 

Memory-Resident User Tasks 

All user-written, memory-resident tasks reside in the area next to the memory-resident sys- 
tem task area. 

Partial Bit Maps 

The partial bit maps for all disks except the system disk reside beiow the memory resident 
tasks. 

Buffer Table Area 

The buffer table area (BTA) is aliocated immediately after the memory-resident user tasks. 
This expandable area includes buffers used for handling input and output for devices. 

The rest of memory is availabie for user tasks, language processors, and utilities. The user 
dynamic memory is allocated to tasks from the end of physical memory to allow the buffer area to 
expand. 

1 .1 .1 System Memory Mapping 

The hardware map option provides three map files; each defines up to 64K (K equals 1024) bytes of 
logical memory space. This space can be located anywhere in the 2048K-byte TILINE address 
space and can be divided into as many as three segments. 

Each map fiie provides three 16-bit bias registers (B1, B2, and B3) and three limit registers (LI, L2, 
and L3). The limit registers contain values that define the lengths of the three segments. These 
segments form the 64K bytes of logical address space. The bias registers contain values that 
define the physical locations of the three segments. Refer to Figure 1-2 for a view of the logical 
and TILINE address space with map option. The logical addresses in the three segments are 
mapped into TILINE beet (32-byte) addresses. 
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Usually, the operating system dedicates the three map files to software functions. The system 
uses map 0 for operating system code and for facilitating special hardware features. Transfer vec- 
tors for interrupts and XOPs are in map 0. This map is one means of addressing the TILINE™ 
peripheral control space and read-only memory (ROM) loader. The TILINE peripheral control space 
is a range of TILINE addresses reserved for access to TILINE device controllers. After setting up a 
map file, a user might also access TILINE peripheral control space using long-distance instruc- 
tions. The ROM loader is a program that executes during IPL to load the operating system into 
memory. 

Both system tasks and user tasks use map 1. The long-distance instructions use map 2 to access 
memory outside the segments currently mapped into the logical memory space. 

1.1.2 Fundamental Structure of DNOS 

The fundamental structure of DNOS is the job structure. A job is a collection of cooperating tasks 
(programs) that you initiate or a program automatically initiates to perform one or more functions. 

The task structure is within the job structure. Many of the DNOS system tasks are queue servers, 
tasks dedicated to processing entries on queues. Queues and queue servers play an important 
role in maintaining system flow. For storing system data, DNOS maintains a set of system files. 

1.1. 2.1 Job Structure. A job is the fundamental entity that receives logical resources. DNOS 
maintains a job status block (JSB) for each job in the system. The JCA is a block of memory that 
contains control information for a specific job including the job’s priority, name, ID, and related 
information. The JSBs are created in the system table area as a linked list for the jobs in the 
system. 

The JSB provides a link to the job communication area (JCA), which contains a queue of the tasks 
in the job, the semaphores defined for the job, and their job-local information. Semaphores pro- 
vide synchronization of tasks within a job. The JCA for the job currently executing is kept in 
memory. 

1.1.2.2 Tasks. A task is a program that executes under control of the operating system. It con- 
sists of an address space, a program counter, a workspace pointer, and a status register. At least 
one task exists for each job. 

Associated with each task is a task status block (TSB), which is a block of memory containing 
information about the task. The TSBs within each job are on a task queue located in a JCA. Each 
TSB can be placed on the active queue, the walting-on-memory (WOM) queue, or the waiting-for- 
table-area queue, according to the priority order within the job. 

Figure 1-3 shows the DNOS task structure. 


TILINE is a trademark of Texas Instruments Incorporated. 
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System Table Area JCA 



Figure 1-3. DNOS Task Structure 


1.1.2.3 Queue Servers. Information queues and queue servers are important concepts in 
DNOS. A queue is a first-in, first-out list of data to be processed. In DNOS, each queue consists of 
a queue anchor and the queued blocks of data in memory. The queue anchors are located in the 
memory-resident nucleus and In the JCAs. Each queue anchor contains the address of the newest 
and the oldest queue entries. Each data item or block is linked to the next data item or block in the 
queue. 

A queue server is a task that processes its associated queue. Placing an entry in the queue acti- 
vates the queue server. Operating as a system task under DNOS, the queue server dequeues an 
entry and then processes it. The queue server continues to dequeue and process queue entries 
until the queue is empty, at which time the server suspends itself or terminates. 

Figure 1-4 shows the DNOS queue structure. 

1.1.2.4 System Files. Various functions of DNOS use system directories and files. Some are 
required if you choose certain options; otherwise, you can remove them. Also, other software sys- 
tems and the languages used with DNOS place S$ files on the system disk. Remove these only if 
you are sure your environment does not need them. 

The system disk Is the disk from which IPL Is done. It is known by the device name set during sys- 
tem generation. For example, if IPL is done from DS04, the file .S$CMDS is the same as 
DS04.S$CMDS. 
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Figure 1-4. DNOS Queue Structure 


DNOS functions use the following directories: 


Directories 

.S$CDT 

.S$CMDS 

.SSEXPMSG 


.S$MSG 


Description 

Files used by the system to process keyboard bids at devices. 

Command procedures provided with DNOS to access the utilities 
using a System Command Interpreter (SCI) environment. 

Key indexed files (KIFs) of expanded error and status messages. 
If you remove this directory (your option), you cannot use the 
question mark (?) key to display details on the screen when a 
message appears. 

Relative record files of basic error and status messages. If you 
remove this directory (your option), all messages appear in abbre- 
viated form, as in the following: 

SVC-INTERNAL CODE > 0027 .PRINT.OUT. 
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.S$SDTQUE 

Files of spooler data, one for each generated system. Do not 
delete these unless you deleted the generated system or you 
need to recreate one of the files. 

.S$SGU$ 

Files created by system generation. You can delete subdirecto- 
ries for systems no longer in use, but you should keep those for 
systems in use. For further information about these files and 
directories, refer to the DNOS System Generation Reference 
Manual. 

.S$SYSLIB 

Overlay management for automatic overlay loading. 

.S$SYSTEM 

Special systems programming command procedures and the 
software configuration history file. Section 12 describes these 
procedures. 

.S$USER 

Directory with subdirectories for each user ID defined for the 
system. Each subdirectory contains user synonyms and logical 
names; you must not delete any of these subdirectories. The 
SYSTEM and SYSMGR user IDs are created during IPL. 

.SCI990 

Linkable object for the SCI interface {S$) routines. 

)S functions use the following files: 

Files 

Description 

.S$ACT1, .S$ACT2 

Accounting log files. You need these if the accounting option is 
enabled. You cannot modify the file currently in use by the 
system. 

.S$CLF 

Capabilities list file used by SCI. Used in conjunction with the 
S$USER directory. 

.S$CRASH 

Crash file to which a system crash can be written. 

.S$DIAG 

File used by online diagnostics when checking the state of the 
disk. 

.S$IPL 

System loader. 

.S$ISBTCH 

Initial batch stream executed during the initialization of the sys- 
tem after an IPL. 

.S$ISLIST 

Listing file for .S$ISBTCH. You can delete this file if you do not 
need the listing. 

.S$LANG 

Languages program file. 
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.S$LOG1, .S$L0G2 System log files used to record error and status information 

about the active system. You cannot modify the file currently in 
use by the system. 

.S$MVI File used by the Modify Volume Information (MVI) processor to 

record changes to the disk. 

.S$PWCS Image file for performance tools microcode. This file is present if 

the DNOS performance package is installed. 

.S$ROLLD.S$ROLLA System roll file used for swapping segments from memory. 

.S$SCA File of information about users that is used by the log-on task 

and SCI. 

.S$SECURE Program file containing support programs for file security. 

.S$SHARED Shared program file, used for sharable procedures and special 

tasks provided by the system. This program file reserves task IDs 
and procedure IDs >00 through >2F for software provided by 
Texas Instruments. All other IDs are intended for users. 

.S$SHIP Kernel program file for the system shipped to the users. You can 

delete this file if you use a different system as the standard 
system. 

.S$UTIL System utilities program file. 


p^' 


1.2 CHANNELS FOR DNOS FUNCTIONS 

DNOS functions use the following channels. Each channel is served by an owner task in the 
S$UTIL program file. 

Files Description 

.S$ACCCHN Channel that processes accounting file entries. 

.S$DSTCHN Channel used by the spooler device scheduler. 

.S$MAIL Channel used for the Create Message (CM) function and other 

SCI message functions. 

.S$OPER Channel used for system operator functions. 

.S$SPOOL Channel used by the spooler. 

.S$XBJ Channel used for processing the Execute Job (XJ) and Execute 

Batch Job (XBJ) commands. 
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1.3 SYSTEM FLOW 

The following paragraphs describe how the operating system responds to requests for service. 
Figure 1-5 shows the flow of control and information In DNOS. 
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Figure 1-5. DNOS System Flow 
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1.3.1 Initial Program Load (IPL) 

System operation begins with iPL. The IPL program is loaded into main memory and performs 
housekeeping functions (such as determining the size of physical memory and initializing physi- 
cal memory). The IPL program then relocates into upper memory and reads the kernel into lower 
memory. Next, the IPL program performs a variety of system initialization functions. The operating 
system is then activated. 

1.3.2 System Idle State 

DNOS enters the idle state immediately after IPL and when no programs or users require system 
services. However, the logical structure of the system changes dynamically when tasks are exe- 
cuted under control of the operating system. 

1.3.3 Task Activation 

Bidding a task is the process of preparing a task for execution. This process involves building and 
initializing the necessary data structures and activating the task. If the task procedural segments 
are already in memory, the system checks to see that the task is not being killed and that its job is 
not terminating. If these conditions are met, the task is placed on the active queue. Otherwise, 
task activation aborts. 

If the task procedural segments are not in memory, the task is put on the waiting-on-memory 
(WOM) queue to be processed by the task loader. After the task is loaded into memory, the checks 
described for tasks already in memory are performed. Either the task is placed on the active queue 
or task activation aborts, as appropriate. 

^ 1.3.4 Task Scheduling 

The task scheduler places tasks into execution. First it selects a task to execulie; then, it instructs 
the central processing unit (CPU) to begin executing the task. The task executes until it releases 
control of the CPU. Then, the scheduler selects the next task for execution. 

Each JCA contains a queue of TSBs for tasks ready to execute in priority orde '. Each JSB carries 
the priority of the highest-priority task on its active queue; the queue of active JSBs is ordered by 
this priority. 

The scheduler selects the highest-priority active task for execution. When a task reaches the end 
of its allotted execution time, its TSB goes back to the JCA active queue if the task is to remain 
active; the task remains unqueued if it is to be suspended. When a task suspe nds, the scheduler 
might need to change the priority of the highest active task in the JSB and reorder the JSB on the 
JSB queue. 

1.3.5 Time Slicing 

Time slicing is the technique of executing each task in turn for a specified period of time. The 
clock interrupt processor controls timing. The clock interrupt routine counts the number of clock 
cycles during task execution. When the count reaches a specified number, the routine 
reschedules the task. Each clock tick is either 8.33 milliseconds (for 60-Hertz line frequency) or 10 
milliseconds (for 50-Hertz line frequency). 

1.3.6 XOP Processing 

When the scheduler places a user task into execution, the task controls the CPU until its time 
slice ends. The only exceptions are when an external interrupt occurs or a task issues an XOP 
instruction. The I/O subsystem activates immediately in response to a device nterrupt. A context 
^ switch occurs when an XOP instruction is issued. 
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When an XOP 15 is issued, control passes via the XOP transfer vector table to the SVC decoding 
routine; this routine is the XOP processor for XOP 15. It determines which SVC is desired by 
decoding the SVC code in the call block and then relinquishes control to the SVC processor. 

If a queue server processes the request, the SVC preprocessor buffers the call block into the sys- 
tem table area and queues the buffered call block onto the proper queue. This activates the asso- 
ciated queue server task and suspends the task that issued the SVC. If system code that Is not a 
queue server processes the request, the SVC is completed and control returns Immediately to the 
task that issued the SVC. 

1.3.7 Execution Priorities 

The scheduiing of DNOS tasks is based on run-time priority. Run-time priorities have a range of 0 
(high) through 255 (iow). To caiculate a run-time priority when a task is bid, DNOS must first look at 
the installation priority of the task. An instaiiation priority is assigned to a task when it is installed 
in a program file. When assigning run-time priorities, .DNOS differentiates between tasks that are 
either priority 0 or reai-time tasks and those that are not. 

The run-time priority of real-time tasks and^priority 0 tasks is identicai to their instaiiation 
priorities. 

The run-time priority of ali other tasks is influenced by the following three factors: 

• The instaiiation priority of the task (1 , 2, 3, 4) 

• The mode of the task (whether foreground or background) 

• The priority of the job under which the task Is running 

Be careful to note that the installation priority given a task (1, 2, 3, 4) that is not a priority 0 or reai- 
time task is relative. Such tasks normally have run-time priorities between 128 and 255. 

The run-time priority of a real-time or priority 0 task is the same as its installed priority. Therefore, 
a system task with an installed priority of 0 has a run-time priority of 0. A real-time task with an 
installed priority of 56 has a run-time priority of 56. 

System tasks usually have an installed priority of 0. Real-time tasks have an installed priority 
range between 1 (high) and 127 (low). Therefore, run-time priorities are also in the same range. 

The run-time priority of all other tasks is handled in a different manner. Tasks in this group usually 
pick up a run-time priority between 128 and 255 (refer to the paragraph describing dynamic modifi- 
cation of run-time parameters for exceptions). 
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First, DNOS looks at the installed priority (1 , 2, 3, or 4) of the job in which the task is being bid and 
whether the task is executing in foreground or background. When determining wlilch installation 
priority to give a task, you should normally use the following scheme: 

• Assign priority 1 to foreground tasks that are heavily interactive. 

• Assign priority 2 to foreground tasks that are compute-bound. 

• Assign priority 3 to only those tasks that always execute in background, as priority 3 is 
the lowest of the four priority classes. 

• Assign priority 4 to tasks that alternate between an I/O bound state and a compute- 
bound state. This priority level is proper for most tasks in a computing eivironment. The 
run-time priority of a priority 4 task running in foreground is lower than tfiat of a priority 1 
running in foreground task but greater than that of a priority 2 task running in fore- 
ground. 

Second, DNOS looks at whether the task is executed in foreground or background. Any task, 
regardless of its installed priority, is treated as a priority 3 task if you bid it in background mode. 

Third, DNOS is heavily influenced by the priority of the job in which the task is bid (range: 0 (high) 
through 31 (low)). A low-priority task in a high-priority job often has a higher run-time priority than 
high-priority tasks in a low-priority job. For example, a background task in a priority 2 job is 
assigned a higher run-time priority than a foreground task in a priority 29 job. 

1.3.8 Dynamic Modification of Run-Time Parameters 

DNOS allows the dynamic modification of run-time priorities. This is called th(j priority modifi- 
cation option. If you enable this option, the run-time priority of a task varies during its execution. | 

To enable this option, use the Modify Scheduier/Swap Parameters (MSP) SCI command to modify 
dynamic priority range parameters. There is one parameter for each of the four installed task priori- 
ties (1, 2, 3, or 4). Unless you are very familiar with dynamic priority range parame ters, you should 
use the following values when you modify the parameters: 12, 12, 12, 12. These values yield the | 
maximum system performance for most environments. To disable this option, set the parameters 
back to their default values (0, 0, 0, 0). 

If you accept the defaults (0, 0, 0, 0) for the dynamic priority range parameters (refer to the Modify/ 
Swap Parameters SCI command), tasks in this group pick up a run-time priority l)etween 128 and 
255. Modifications to the parameters, however, can yield a run-time priority higher than 128. 

To understand this process, consider the following. As a task executes, an indicator shows 
whether the task is l/C-bound or compute-bound. DNCS uses this indicator to modify the run-time I 
priority of tasks (raising priority for I/O-bound tasks and lowering it for compute-bc und tasks). | 
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The degree to which a run-time priority can vary for tasks depends on the vaiue of the dynamic 
priority range for that priority ciass. For exampie, if you use the MSP command to assign dynamic 
priority range parameters of 8, 12, 0, and 32, the foilowing events occur: 

• The run-time priority of priority 1 and priority 2 tasks wouid vary by plus 12 (I/O bound 
tasks), since 12 is the smallest allowed variation. 

• The run-time priority of priority 3 would be unaffected. 

• The run-time priority of priority 4 tasks would vary by plus 24. 

Test results show that modifying dynamic priority parameters can improve the mean response 
time of DNOS in some environments. 

An aging factor can further modify the run-time priority. The priority of an older task is raised 
slightly more than the priority of a newer task. To raise the priority, the power of 4 that represents 
the execution time in seconds is used. That is, a task that has executed for 4 seconds is raised 1 
priority level; one that has executed for 16 seconds is raised 2 levels, and so on. At the end of 18 
hours of execution, the priority of a task is raised 8 levels. 

1.3.9 Task Termination 

A task terminates when one of the following occurs: 

• The task issues a termination SVC. J 

• Another task issues a Kill Task SVC for this task. 

• The task aborts by executing an illegal operation. 

If the task specifies end action (execution after abnormal termination), execution resumes at the 
specified end-action address for a certain length of time. Otherwise, the task releases its 
resources and goes to the terminate task queue, where the termination processor task 
deallocates it. 

1.3.10 Clock Interrupt Processor 

The clock interrupt processor gathers performance statistics, keeps track of time, and decides 
when a system time unit has expired for the executing task. The time and date appear in the fol- 
lowing form: year, day (Julian), hour, minute, second, and tick (8.33-millisecond unit). A 32-bit tick 
counter also keeps track of time in clock ticks. The time, date, and 32-bit tick counter are updated 
on each clock tick. 

1 .3.1 1 Internal Interrupt Processor 

Instruction execution errors (for example, illegal opcodes and privileged instructions) cause inter- 
nal interrupts (interrupt level 2). The internal interrupt processor handles these interrupts. If an 
interrupt occurs in task code, the processor kills the task or puts it into its end-action code; con- 
trol returns to the scheduler. However, if the error occurs in operating system code, in interrupt 
processing code, or while scheduling is inhibited, the processor calls the system crash routine. 
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1.3.12 System Crash Routine 

When a module detects an internal operating system error, it branches to the system crash routine 
and passes a crash code that indicates the type of error. The crash routine halts the system and 
displays the crash code on the programmer panel of the computer. Pressing HALT and RUN on the 
programmer panel saves the state of the system at the time of the crash and writes an image of 
memory to the crash file on disk. You can then analyze the crash. 


1.4 IPL AND SYSTEM LOADERS 

IPL Is the process of loading the operating system into memory. Before you can enter any system 
command into the system for execution, the IPL procedure must bring DNOS into memory. To per- 
form an IPL, press in sequence HALT and LOAD on the front panel of the computer. For a Busi- 
ness System 300, turn the power off and on to perform an IPL. 

When an IPL procedure completes, the system restart task is bid. The task performs the following 
initialization activities: 

• Defining channels needed by DNOS 

• Assigning system-required global logical names 

• Creating log and accounting files 

• Deleting temporary files 

• Creating the SYSTEM user ID 

The task also performs initialization activities that enable DNOS to offer the security option: 

• It creates the SYSMGR user ID. 

• It creates the SYSMGR access group. (The SYSMGR access group is created only when 
the S$CLF file needs to be created.) 

The IPL process checks to see that the crash file on the system disk is large enough to contain the 
entire system memory image. If the file is not large enough, the IPL process attempts to delete the 
existing .S$CRASH file and creates a larger one. If the IPL process encounters an error when it 
tries to delete the file, the first person to log on the system is shown a message that says that the 
crash file is either too small or it does not exist. 

The file .S$ISBTCH serves as a batch stream for adding unique system procedures that are per- 
formed Immediately following IPL. For example, you can include procedures to assign global logi- 
cal names, initialize certain functions, monitor devices, or delete certain directories. Executing 
.S$ISBTCH also invokes the SCI command procedure M$00. This batch stream executes in a job 
named SYS$INT. For this job, the synonym $$UI is not defined. 
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The following paragraphs describe what happens between pressing the LOAD switch and 
initiating a job from a terminal. 

Three loaders are Involved in an IPL procedure: the ROM loader, the program image loader, and 
the system loader. The ROM loader brings the program image loader into memory from the system 
disk. The program image loader locates the system loader on the disk and loads the system 
loader. The system loader loads the system image and transfers control to the system. The 
following paragraphs discuss each loader in detail. 

1.4.1 ROM Loader 

The ROM loader (bootstrap loader) resides in TILINE peripheral control space starting at location 
> FCOO. You can program this loader to load from devices accessible on the TILINE bus and on the 
communications register unit (CRU). The IPL is performed from a system disk (a TILINE device). 
(This manual does not describe using the ROM loader for other devices.) 

Location >80 contains a negative vaiue that indicates the TILINE device to be used as the load 
device. Location >82 contains the TILINE address of the load device. This address specifies the 
location of the TILINE peripheral control space for loading the TILINE device commands. The 
default is > F800. To ioad the system on a 990/10 or 990/12 computer (using a disk controller) at an 
address other than > F800, you must change the contents at location > 82. 

Refer to the ROM Loader User’s Guide for a description of how to use the ROM loader and how to 
modify the value for the default load device. 

1.4.2 Program Image Loader 

The program image loader resides on track 1 of every DNOS-formatted disk that was specified as a 
system disk. It can load any stand-alone program from an image file or object file on disk into 
memory. The following criteria determine the program to be loaded: 

• If the diagnostic flag in the volume information is nonzero, the diagnostic task is loaded 
and the flag is reset to zero. Section 2 describes the volume information in detail. 

• If no diagnostic is specified, the loader checks to see if the file pathname of either a 
primary or a secondary system loader is specified. If so, the image loader loads the sys- 
tem loader indicated by the flag, as follows: 

0 — Load primary 

1 — Load secondary 

- 1 — Load secondary 

If the flag equals - 1 , the image loader resets the flag to 0. 

• If no system loader is specified, the image loader loads the system image indicated by 
the image flag, which is used in the same manner as the system loader flag. 

The program image loader normally loads a program image starting at memory location > AO. This 
default load address is stored in the second word of the loader. You can change it by using the 
Modify Absolute Disk (MAD) command. 
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1.4.3 System Loader 

The system loader resides on the system disk in an image file called S$IPL. The program image 
loader loads it into memory. The system loader executes with interrupts masked to level 2, inhibit- 
ing Interrupts from devices. Once loaded into memory, the loader initializes physical memory and 
determines the actual size of physical memory in the computer. 

As the loader finishes a particular phase of the load process, it displays the phase on the program- 
mer panel Indicators, starting at the leftmost indicator. 

The following lists in sequential order the phases of the load process: 

Phase 

Number Description 

1 Loader relocation complete 

2 Successful opening of kernel program file 

3 Successful loading of root, verification of system version, and loading 
of writable control source (WCS) 

4 Successful loading of special table areas 

5 Successful initialization of system overlay table and crash file 

6 Successful loading of JCA segments 

7 Successful loading of DSRs and scheduler 

8 Successful loading of memory-resident system tasks 

9 Successful loading of user memory-resident tasks 

The loader first relocates itself into high-order physical memory. It then opens the program file 
that contains the kernel and loads the WCS (when applicable). Next, the loader loads the system 
root and initializes the crash file. If a crash occurs during the remainder of the load operation, the 
crash file contains useful information about the crash. Special table areas are loaded next, 
followed by the system job JCA, DSRs, the scheduler, and memory-resident system tasks. 

Next, the loader performs some special initialization, such as the following: 

• Determining which of the disk drives defined is the disk from which the system was 
loaded and marking it as the system disk 

• Installing the system disk 

• Creating file descriptor blocks (FDBs) for the system files used during the load process 
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The next step in the load process is to install all online disk volumes. The final phase of the loader 
execution is allocation of the buffer table area (located in user memory, immediately following the 
memory-resident part of the operating system and all memory-resident tasks) and Initialization of 
the system anchors for the free user memory of the buffer table area. The memory containing the 
loader is considered part of user memory. After all initialization is performed, the loader transfers 
control to the power-up interrupt processor of the operating system. 


1.5 DNOS SUBSYSTEMS 

DNOS includes several subsystems that implement capabilities including job management, seg- 
ment management, name management, and interprocess communication (IPC). User commands 
interpreted by SCI can access these capabilities. User programs access these capabilities by 
executing SVCs. The following paragraphs describe these subsystems and the relevant 
commands. 

1.5.1 Job Management 

A job is an entity that performs a user-defined function within the system. It can Include one or 
more tasks, and it can be either interactive or batch. 

An interactive job is initiated when a user logs on at a terminal. You can also initiate an interactive 
job by entering an Execute Job (XJ) command. The terminal specified in response to the STATION 
ID prompt is the terminal used for interaction. 

A batch job consists of one or more tasks that do not require interaction with a terminal and that 
execute in the background. The commands that direct the execution of the task or tasks of the job 
are supplied in a file. To initiate a batch job, enter an Execute Batch Job (XBJ) command. 

Job management is the subsystem of DNOS that performs the system functions required to initi- 
ate, execute, and terminate jobs. Management of resource allocation by jobs provides a level of 
protection between jobs. Once a job is initiated, execution of the tasks of a job is independent of 
the execution of tasks within other jobs. 

1.5.1.1 Supervisor Call (SVC). The Job Management Request SVC is the interface of a task with 
the job management subsystem. This SVC performs the following job management operations: 

• Create Job 

• Halt Job 

• Resume Job ^ 

• Modify Job Priority 

• Map Job Name 

• Kill Job 

• Get Job Information 
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A task requests creation of a job by requesting a Create Job operation. If the request is valid, the 
job is created with a unique job ID. This ID is used throughout the system as the identifier of the 
new job. The job is set into execution if the job limit is not exceeded. If the limit is exceeded, the 
job is queued, waiting for an executing job to terminate. 

Various control capabilities are available for interpreting and modifying the status of jobs. The 
use of these capabilities depends on the requester’s ability to prove ownership (by user ID) of the 
job. The types of requests available include those to show job status, kill the job, halt the job, 
resume the job, and modify job priority. 

1.5.1.2 SCI Commands. The following commands are available through SCI to execute jobs 
and to perform various operations on jobs currently executing under the user’s ID: 

Execute Batch Job (XBJ) 

The XBJ command creates a job having batch SCI as its initial task. 

Execute Job (XJ) 

The XJ command creates an interactive job with operating parameters differing from those of 
the creating job. 

Show Job Status (SJS) 

The SJS command displays the status of any jobs currently executing under the user’s ID. 
Halt Job (HJ) 

The HJ command suspends a job currently executing under the user’s ID. 

Kill Job (KJ) 

The KJ command forces termination of a job currently executing under the user’s ID. 

Resume Job (RJ) 

The RJ command resumes execution of a job that has been previously halted. 

Modify Job Priority (MJP) 

The MJP command modifies the priority of a job while it is executing. 

List Jobs (LJ) 

The LJ command allows you to list the current status of a particular job or all jobs on the 
system. 

1.5.2 Segment Management 

The segment management feature enables tasks to dynamically change the current segment set 
mapped by the task. This feature also enables a task to guarantee access to a segment until it is 
no longer needed and enables a task to write segments to disk. 

Segmentation allows more than three segments of a task to be in memory. The program can map 
three segments in the program address space simultaneously. This feature allows faster execu- 
tion speed than overlay loading. If enough memory is available, it also enables a program to 
exceed the 64K-byte address boundary. 
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The two types of segments are memory-based 4nd disk-based. The Create Segment operation of 
the Segment Management SVC creates a memcjry-ba'sed segment at run time. The newly created 
segment is mapped into one of three segments tjy specifying the segment position or by replacing 
an existing spare one using the segment run-tirine ID. Segments not in a task address space are 
released from memory if the segment reserve cdunt is 0. The reserve count keeps track of the cur- 
rent usage of the segment. 

The Reserve Segment operation of the Segment Management SVC increments the reserve count. 
For a task to retain access to segments not in the task address space, the user must request a 
Reserve Segment operation. Such segments are reserved until the user requests the Release 
Segment operation of the SVC. | 

A disk-based segment is either a segment installed In a program file or a physical record of a rela- 
tive record file. To install a segment, use the Install Task (IT), Install Procedure (IP), or Install 
Program Segment (IPS) command. One, two, or ^hree segments can be brought into memory when 
the task is loaded for execution. This is acconiplished by the IT command with specification of 
attached procedures. The Change Segment opjeration of the Segment Management SVC loads 
installed segments into memory while the progiiam is executing. The Force Write Segment opera- 
tion can write the disk-based segments that are updateable back to their home file position. 

You can place an unmapped segment physically in memory by requesting a Load Segment opera- 
tion. The Unload Segment operation releases thp segment from memory. The Set Exclusive Use of 
Segment operation prevents other tasks from accessing an unmapped segment. The Reset Exclu- 
sive Use of Segment operation releases the segment from exclusive use. Like a Reserve Segment 
operation, the Exclusive Use of Segment operation ailows a task to retain access to a segment not 
in the task address space. 

The Segment Management SVC supports the foijlowing operations: 

• Change Segment 

• Create Segment 

• Reserve Segment 

• Release Segment 

• Check Segment Status 

• Force Write Segment 

• Set/Reset Reiease/Modifiable Flag 

• Load Segment 

• Unload Segment 

• Set Exclusive Use of Segment 

• Reset Exclusive Use of Segment 
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1.5.3 Name Management 

The following paragraphs introduce the concept of iogical names and describe their uses with 
files. 

1.5.3.1 Logical Names. A logical name is a system variable from one to eight characters long, 
defined by the user. The value of the logical name is a pathname or device name. The parameters 
of the pathname supply related information. A logical name provides a name by which a resource 
is known to the job. The user can reference the logical name instead of the pathname or device 
name. A iogical name also provides a mechanism for passing parameters associated with the 
resource. 

A logicai name may be giobal or job locai in scope. Any user can assign a global logical name that 
is availabie to ali system users. In contrast, a job-local logical name is available only to the 
specific job for which it is defined. 

Logical names permit three extensions to the standard file types: job temporary files, logically 
concatenated files, and multivolume files. A logically concatenated file is a group of files known 
collectively by a single logical name. A multivolume file can exist on one or more disk volumes. 

1.5.3.2 Job Temporary Files. Job temporary files are used only within the scope of a job. These 
temporary fiies are local to the job that is active when the files are created; they are deleted along 
with the job. Any task within the job can access a job temporary file. 

To create a job temporary file, specify the parameters for the file on a Create Logical Name opera- 
tion of the Name Management SVC; then, use the Assign LUNO operation of the I/O Operations 
SVC to assign a LUNO to the logicai name, automaticaily creating the file. 

Access to the file is by iogical name. You can use a job temporary file to accumulate output data 
from multiple tasks or to pass data from one task to another. 

The mechanism used to keep a job temporary file from being deleted gives the file the appearance 
of always having a LUNO assigned. For this reason, operations that require no LUNOs to be 
assigned to the file (that is, DF, MFN, orXE with exclusive use) will not succeed. A volume that has 
a job temporary file currently in use cannot be unloaded until the file has been deleted. 

Job temporary files are implicitly deleted when the job terminates. They can also be deleted by 
releasing the logical name used to access the file. In the event of a system crash, temporary files 
are deleted at the next I PL. 

1.5.3.3 File Concatenation. You can logically concatenate sequential and relative record files 
by setting the values of a logical name to the pathnames of a set of files. Logical concatenation 
aliows access to the set of files In sequence without physically concatenating the fiies. When 
required, you can physicaily concatenate the files via the Copy/Concatenate (CC) SCI command. A 
multifile set is a set of KIFs whose pathnames are the values of a logical name. The files in the set 
are associated in a nonreversible manner, individual components of concatenated and multifile 
sets can be on separate disks. 
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Several restrictions apply to the concatenation of files: 

• The files must be of the same type. 

• The files cannot be special use files such as directories, program files, KIFs, or image 

fiies. ^ 

• Relative record files to be concatenated must have the same logical record size. 

• A concatenation of files cannot contain blocked and unblocked records. 

• You must release any LUNO assigned to a file before concatenating the file. 

• You cannot concatenate a file with itself. 

• You cannot use a logical name at one site to concatenate files at another site. 

Speciai ruies appiy to combining KiFs in a multifiie set. At the first definition of the set, the follow- 
ing rules apply: 

• All but the first file must be empty. 

• No file can be a member of an existing multifile set. 

• All files must have the same physical record size and the same key definitions. 

In subsequent definitions of these sets, the following ruies apply: 

• The same files as in the first definition must be associated in the same order. 

• You cannot omit any of the fiies that were in the originai set. 

• You can add one empty file at the end but not at any other position. 

You can access a KiF of a multifiie set oniy as an unblocked file. 

A multifile set of KIFs permits a larger KIF than one disk can store. When a KiF can no ionger 
expand because of insufficient space on the disk, you can create a new file on another disk. By 
using a logicai name, you can use the two files as one. The second file is, in effect, an extension of 
the first, if the first file contains 5000 physical records and physical record 5001 is required, the 
first physicai record of the second fiie, record 0, is used. 

The foiiowing iists the fiie utiiity operations of the I/O Operations SVC that appiy to concatenated 
and muitivolume sets: 

• Assign LUNO 

• Release LUNO 

• Verify Pathname 
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The Assign Logical Name (ALN) SCI command associates files collectively with a logical name. 
Actual logical concatenation or creation of a multifile set occurs when you assign a LUNO to the 
logical name. You can access a concatenated file only for the duration of the logical name. You 
can specify files by pathname, synonym, logical name, or a logical name and pathname combina- 
tion. However, all forms must resolve to valid pathnames. All files in the concatenation or multifile 
set must be precreated and online when you use the logical name. 

The last file in a concatenation set can be expandable. All other files become nonexpendable until 
the logical name is released orthe job terminates. 

When a single end-of-file (EOF) mark appears at the end-of-medium (EOM), the EOF is masked. 
This allows you to access concatenated files logically as a single file without receiving intermedi- 
ate EOF marks. Note that any intermediate EOF mark not at the EOM is always returned. If you 
encounter two EOF marks at the EOM, a single EOF is returned. 

Several users can access the same concatenated or multifile set if the access privileges permit. 
Two concatenated files are identical when they consist of the same pathnames in the same order. 
An error occurs if any of the precreated files of a concatenated file are being accessed indepen- 
dently. This maintains file integrity. To delete a concatenated file, you must delete the individual 
files. 

To back up individual components of a concatenated file or a multifile set, use the standard direc- 
tory utilities. You cannot back them up by using the logical name. After backing up the files to a 
new medium, you can assign a new logical name to them and use them as before. 

1.5.3.4 Multivolume File Capability. A multivolume file is a concatenated file or a multifile KIF 
set that is made up of files on two or more volumes. The same rules and limitations apply to 
concatenating files on different volumes as files on the same volume. 

1.5.3.5 Stages of Name Definitions. All logical names associated with a given job are located 
in a unique segment in memory. Stages are used to divide the logical names within a name seg- 
ment Into independent groups. The same names can appear in more than one stage, but changing 
the value of a name in one stage does not affect the value of the name in any other stage. 

Each stage within a name segment has a unique stage number between 0 and 255, and each task 
within a job is associated with a stage number. A task is not restricted to this stage. It can enter a 
new stage, and after some time executing there, it can return to its previous stage. Both of these 
operations are subopcodes of the Name Manager SVC. These operations are used by system soft- 
ware and are not documented with the standard user SVC. 

When the first user logs on with a given user ID and job name, a name segment is created and ini- 
tialized with the names retrieved from the file .S$USER.< USER ID>.SYN. Each defined user ID 
has a directory under .S$USER. The files in these directories are used to store name definitions 
while the user IDs are not being used and to recreate stage zero when a user logs on. Initially, only 
stage 0 exists. However, as soon as any foreground SCI task begins executing, it issues an Enter 
New Stage operation. The first SCI task that is bid in a new job initializes stage 1 with the names 
of stage 0 and associates SCI with the new stage. 
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When a user reconnects to an existing job, a similar set of events occurs. LOGON bids the new 
SCI under stage 0; SCI executes an Enter New Stage operation; a new stage number is allocated 
and initialized with the names of its parent stage (stage 0); and the new stage number is asso- 
ciated with the new SCI. Note that even though a user’s disk-resident name file might change 
between the time that he logs on and the time th^t another user reconnects to his job, both users 
start execution with the same name definitions. The reason for this is that stage 0 is initialized 
only once and is never changed. However, if another user logs on with the same user ID and job 
name but does not reconnect, he begins execution with the current names in the synonym file 
since he is creating a new job whose name segment has not been initialized. 

After SCI has finished initializing itself, a user can begin executing commands and programs. Any 
task which is bid by SCI and runs in the foreground begins executing with the same stage number 
as its parent task, SCI. This is true for all command' processors that are bid by the .BID and .RBID 
primitives and for all user tasks that are bid via the Execute Task (XT) command. All command 
processors that are bid by the .QBID and .DBID primitives and all batch streams that are bid via 
the Execute Batch (XB) command begin execution in a new stage. SCI handles the latter case by 
executing an Enter New Stage operation and performing a regular bid. After the new task has 
begun executing in the new stage, SCI executes a Return to Previous Stage operation. A task bid 
in this fashion cannot change the name definitions of its parent stage. 

When a user executes the Quit SCI (Q) command, SCI executes a Save Names operation. This 
operation causes the names associated with the stage of the requesting task to be saved in a 
specified file. For SCI, this file is always .S$USER.< USER ID> .SYN. Even if more than one user is 
reconnected to a job, this operation is performed after each user logs off. The file will reflect the 
name definitions of the last user to log off. Therefore, it is necessary for users to cooperate when 
sharing a a single name segment. 

1.5.4 Interprocess Communication (IPC) 

IPC provides communication between two or more tasks. Information passes through 
communication channels, and IPC is responsible for managing channel activity. 

1. 5.4.1 Channel Definition. A channel is a path through which data flows between two or more 
tasks. A single owner task controls each channel. One or more other tasks, called requesting 
tasks, can exchange data with the owner task. The scope of a channel can be global, job local, or 
task local, as follows: 

Global Scope 

A channel having global scope is potentially accessible by any task in the system. The owner 
task is nonreplicatable and cannot be bid automatically by an Assign LUNO (AL) SCI com- 
mand or a corresponding SVC. Multiple tasks, can concurrently use a global channel that 
permits shared access. 

Job-Local Scope 

A channel having job-local scope is accessible by any task in the job. The owner task is repli- 
catable, one copy per job. The channel can be created as sharable, and the owner task can be 
bid automatically when the first AL command or corresponding SVC assigns a LUNO to the 
channel. 
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Task-Local Scope 

A channel having task-local scope is accessible within a task. The owner task is replicated 
for each requester task. By definition, the channel is not sharable, and the owner task is bid 
automatically when the first AL command or corresponding SVC assigns a LUNO to the 
channel. Each requester task can Independently assign a LUNO, open the channel, perform 
I/O, close the channel, and release the LUNO. 

1.5.4.2 Channel Creation. Creating a channel consists of the following steps: 

1. Install the channel owner task in an existing program file or in a newly created program 
file. For a job-local or task-local channel, you must Install the owner task as a 
replicatable task. The owner task of a global channel is not replicatable. 

2. Create the channel by executing a Create IPC Channel (CIC) command or the corre- 
sponding SVC operation. This creates the channel with the specified characteristics. 

1.5.4.3 Channel Characteristics. DNOS channels can be defined as symmetric channels or 
master/slave channels. Symmetric channels function with simple read and write requests, where 
one correspondent on the channel issues a read and another issues a write. The data written 
passes to the reader’s buffer when a pair of requests match. In a master/slave channel, the master 
task receives the entire buffered SVC block for processing. The master (owner) task processes the 
block and returns the resulting block to the requesting (slave) task. 

Symmetric Channel Activity. Symmetric channels communicate messages or data in a rela- 
tively restricted fashion. Tasks can be written to exchange information or facilitate use of com- 
mon resources. The operations addressed to the channel by such tasks are limited to Open, 
Close, Read, Write, Read Status, and Write EOF. 

When a task opens the channel, the access privileges requested are checked against those pre- 
viously granted to other users of the channel. The same rules apply for channels as for other 
resources when granting or denying access. For example, if one requesting task opens a channel 
with privileges of exclusive all, no other task can open the channel. Shared access, which allows 
both Read and Write operations by all channels, is appropriate for most Open operations. 

The channel definition can require more restrictive access privileges than a task specifies. A 
requesting task can open a symmetric channel established as a nonshared channel in any mode; 
however, the channel functions with only one task at a time. This is necessary for a symmetric 
channel since the owner task has no way of differentiating requesting tasks from each other. 

Any of the following can issue a Close: an owner, a requesting task, or the system when process- 
ing an abnormal termination by a task on the channel. When a Close is issued by (or for) a request- 
ing task, IPC processes the Close and the channel closes for that task. 

On other operations to a symmetric channel, IPC must find a match before the operation is per- 
formed. That is, one task must issue a Read and the other a Write before either operation will be 
processed. If a mismatch occurs, both the requester and the owner tasks are informed of the error. 


2270510-9701 


1-25 



DNOS System Overview 


S 


When an owner issues a Close, IPC processes the request and the channel is marked as dormant 
for ail tasks for which it is currently open. This setting causes requesting tasks to receive errors 
on any operation except Open and Close. When a requesting task on a dormant channel issues a 
close, the channel becomes a closed channel for that task, and it is available to be opened. 

Master/Slave Channel Activity. A master/slave channel Is established when the owner task pro- 
cesses all requests from requesting tasks. The master/slave owner task can be written in assembly 
language using the Master Read, Master Write, and Read Call Block operations described in sub- 
sequent paragraphs; it can also be written in a high-level language with subroutine support to 
access these operations. 

When accessing a master/slave channel, a requesting task may need to pass a set of parameters 
to the master task. The user can specify these parameters as part of an Assign Logical Name 
suboperation of the Name Manager SVC. Then, DNOS can pass them to the owner task as part of 
an AL command or a corresponding SVC. 

To receive such parameters, an owner task may process Assign LUNO operations from requesting 
tasks. The owner receives the request with Master Read. The owner task then requests a Master 
Write of the assign block. Owner tasks that process assigns also process Release LUNO calls. 

The owner task can process I/O Abort requests and all I/O Utility requests. You must specify these 
options in the Create IPC Channel (CIC) command. 

While using a master/slave channel, the owner task processes I/O operations to a channel from ^ 

requesting tasks. The owner task issues a Master Read to obtain a request for processing and 
issues a matching Master Write to return messages or status information to the requesting task. 

IPC performs several operations for the master/slave channel as It does for the symmetric chan- 
nel. In particular, IPC deals with an Open or Close issued by an owner task as described for 
symmetric channels. The owner Open specifies the channel access privileges in a manner consis- 
tent with I/O resources. The owner task processes Open and Close operations from a requesting 
task processed by the owner task. IPC modifies some internal counts to keep track of requesting 
task Open and Close operations when the owner executes a Master Write of the Open or Close 
block. 

IPC passes to the owner task all I/O operations issued to the channel by the requesting task. The 
operations are processed accordingly. The owner task uses the following operations exclusively: 

• Open 

• Close 

• Master Read 

• Read Call Block 

• Master Write 

• Read Status 
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1. 5.4.4 IPC Supervisor Calls (SVCs). The IPC operations are a subset of the operations that the 
I/O Operations SVC provides, in addition to those iisted in the preceding paragraph for nnaster 
tasks, the foilowing operations appiy to iPC channeis: 

• Create iPC Channei 

• Deiete iPC Channei 

• Open 

• Symmetric Read 

• Symmetric Write 

• Write EOF 

• Ciose 

1.5.4.5 IPC SCI Commands. The foiiowing SCi commands support iPC capabilities: 

Create iPC Channei (CiC) 

The CiC command creates a global, job-local, or task-local channel. A global channel is 
accessible by any task in the system, and the owner task is nonreplicatable. A job-local chan- 
nel is accessible by any task in the job, and the owner task is replicatable. The owner task of 
a task-local channel is replicatable for each task in any job. 

Delete IPC Channel (DIC) 

The DIC command deletes the disk-based definition of the channel specified. 

Show Channel Status (SCS) 

The SCS command displays information about a specified active channel. This information 
includes channel owner, type of channel, scope of channel, maximum message length, 
shared or not shared scope, number of current assigns, number of current opens, and current 
access privileges. 
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2.1 FILE ORGANIZATION 

DNOS provides disk fiie support for applications and system programs. A fiie is a named and 
organized coiiection of records. Disk fiies are written on any of several disk media used with 
DNOS. You can access the files through the I/O subsystem. The following paragraphs describe 
the types of files, ways of protecting and sharing them, and their characteristics. 

2.1.1 File Types 

DNOS supports three types of disk files: 

• Sequential files 

• Relative record files 

• Key indexed files (KIFs) 

Relative record files include three special usage groups: 

• Directory files 

• Program files 

• Image files 

2.1.1.1 Sequential Files. In a sequential file, the order in which the records are written deter- 
mines record organization. You cannot alter the record sequence by adding or deleting records 
except in the following cases: 

• You can add records in sequence following the last record in the file. 

• You can rewrite a record if the record length does not change. 

On a blank-suppressed file, the blank-suppressed record length must not change during a rewrite 
operation; the internal size of the record must be the same. Records in a sequential file are of 
variable length, and you access the records serially (record 0 first, record 1 next, and so on). 
Records are accessed in the order in which they were originally written. 

Encountering an end-of-file (EOF) on a read of a sequential file indicates that the file is positioned 
after the last record. 
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2.1. 1.2 Relative Record Files. A relative record file consists of records that are identified by 
position. In effect, the file is a string of logical records, each accessed by a record number. The 
first logicai record is record 0. Therefore, to access the tenth record, you should enter 9 in the 
appropriate fieid of the I/O supervisor call (SVC) block. You can access relative record fiies 
sequentially by placing a starting vaiue in the record number field of the I/O SVC block. DNOS 
automatically increments the record number after each read or write. The range of record numbers 
is from 0 to one less than the number of records In the file. The upper limit is 16,777,216. Records 
in a relative record file are of fixed iength. The length is specified when the file is created. 

DNOS converts the record number to a physical address on the disk (track and sector). It can 
directly access any record with one disk access. 

Relative record files can be blocked or unblocked. Generally, blocking aliows faster processing. 
You can delay actual disk transfers of memory buffers for biocked reiative record files. Once a 
buffer for a block is ailocated in memory and the block is read from disk, ali Read operations from 
that block reference the memory buffer for the block. Unless you select the immediate-write 
option, information directed to records already in rnpmory is not written back to disk until DNOS 
requires the memory space aliocated to the blocking buffer or until the file is ciosed. 

When DNOS reads an EOF on a relative record fiie, the record number is used but not incremented 
in the SVC biock. 

2.1. 1.3 Key Indexed Files (KIFs). A KIF consists of data records that you can access by con- 
tent. You can define various fields within a record as a key. Each record can have up to 14 keys, 
with access through each key independent of the other keys. For example, the records in an 
empioyee file might be accessed by empioyee ID, employee name, and employee social security 
number. 

In addition to random access by key value, KIFs have the following features; 

• You can access records sequentiaiiy in the sort order of any key. 

• At fiie creation, you can give a key the attribute of allowing duplicates (that is, of allow- 
ing two or more records in the file with the same value for this key). 

• At file creation, you can give a key the attribute of being modifiable. This allows you to 
change the key value when you write a record. Also, a modifiable key value can be miss- 
ing in the record but added later on a rewrite. Note that you cannot assign this attribute 
to the first (primary) key. 

• Key fields can overlap if their attributes match. 

• A key can be up to 100 contiguous characters long. 

• Records can be of variable length and can change in size on a rewrite. 

• Positioning on partial keys is allowed. 

• Records are automatically blank compressed. 

• Record-level locking (temporary exclusive-all access) is supported. 
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• The file can grow in size. 

• Preimage logging of modified blocks maintains file integrity. As a result, system 
crashes and power failures cause the loss of only the last I/O operation. 

• A KIF cannot contain records of odd or zero length. 

• The EOF on a KIF is analogous to the EOF on a relative record file. 

2.1 .1.4 Special Usage Files. DNOS supports three special types of relative record files: 
Directory File 

Contains information necessary to locate other files and descriptive information about those 
files. It does not contain user data. 

Program File 

Contains executable programs or segments In memory image form. A program file usually 
contains more than one program. 

Image File 

Has a logical record size that equals the physical record size, which In turn equals the disk 
sector size. Image files usually contain a memory image of some code. These files are 
designed so that a program image can be read Into memory in one disk access. 

2.1.2 File Protection and Sharing 

DNOS ensures disk file integrity and allows you to control the use and modification of files by 
means of the following features: 

• Delete and write protection 

• Record locking 

• Access privileges 

• Special usage file protection 

2.1 .2.1 Delete and Write Protection. Standard I/O calls modify the delete and write protection 
file attributes. Files are initially created without protection. You must make a subsequent I/O call 
to change the protection status. 

An attempt to write to or delete a write-protected file fails and returns an error code. (Write protec- 
tion includes delete protection.) These protective attributes are not intended for file security. 
(Nonprivileged SVCs are available to remove write and delete protection.) Instead, they provide 
protection against user error or program flaws that might otherwise destroy valuable data. 
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2.1.2.2 Record Locking. Record locking restricts access to a record in a file. This means that 
although several users share access to a given file, you can lock individual records within the file 
to provide exclusive (single-user) read and write access. This is not a security feature, since any 
file user can unlock a locked record; however, this feature can ensure that record updates occur 
one at a time. For example, inventory files can be accessible from several terminals. Record lock- 
ing can prevent two or more users from attempting to update a record simultaneously, causing an 
undetected loss of one of the updates. 

2.1.2.3 Access Privileges. To assist intertask I/O synchronization, DNOS supports several dif- 
ferent access modes for all I/O resources. These modes define the relationship between logical 
units and resources and prevents conflicting accesses by other logical units. Four access modes 
apply to files. Enforcement of file access privileges is through the Open, Open Rewind, and Open 
Random operations of the I/O Operations SVC. The SVC fails if you request an operation with a 
conflicting privilege level. You can change access privileges if no access conflicts result. 

With respect to access privileges, a Write operation is any operation that alters the contents of a 
file. The access privileges, which conform to the American National Standards Institute (ANSI) 
standard, are as follows: 

• Read-Only — Allows the calling program to read but not write. Gives other programs 
read-only, shared, and exclusive write access. 

• Shared — Allows the calling program to read and write. Gives other programs read-only 
and shared access. 

• Exclusive write — Allows the calling program to read and write. Allows other programs 
to read but not write. 

• Exclusive all — Allows the calling program to read and write. Does not allow other pro- 
grams to have access. 

The Open, Open Rewind, Open Random, and Modify Privileges operations use bits 3 and 4 of the 
user flags in the I/O SVC block to select the following access privileges: 


Code 

Meaning 

00 

Exclusive write 

01 

Exclusive all 

10 

Shared 

11 

Read only 


2.1 .2.4 Special Usage File Protection. To prevent accidental use of special usage files (pro- 
gram, directory, and image files) as data files, you must set two flags in the I/O SVC block for the 
Assign LUNO operation. These flags indicate whether the LUNO is being assigned to a program 
file, a directory, an image file, or a file with no special usage. You must set the proper flags to set 
the LUNO; otherwise, an error code is returned. The flags are bits 1 and 2 in byte 16 of the I/O Oper- 
ations SVC block. For further details, refer to the DNOS Supervisor Call (SVC) Reference Manual. 


2-4 


2270510-9701 



Disk and File Organization 


2.1.3 File Characteristics 

The following paragraphs describe these characteristics of DNOS files: 

• Record blocking 

• Saving disk space 

• Immediate write 

• Temporary attribute 

• Expandability 

• End-of-file 

2.1.3.1 Record Blocking. A file consists of a collection of data entities called logical records. 
The logical records do not necessarily correspond to the physical records (that is, to the physical 
division of data on the disk). Logical records are the data groupings of a file as seen by a program. 
Physical records are the buffers physically transferred between memory and disk. 

The length of the logical records within a file can be constant or variable, depending on the file 
type. For relative record files, logical records are of fixed length. This makes it possible for the 
system to calculate the physical position of any logical record relative to the beginning of the file. 
This characteristic makes possible random access of a logical record in relative record files. 

Sequential files and KIFs allow variable-length logical records. For KIFs, the logical record length 
is always an even number of bytes. For sequential files, the logical records can be any number of 
bytes. Including zero. 

When you create a file, you must specify the logical record size. For relative record files, the size 
must be exact. For sequential files and KIFs, the record size is used to calculate the amount of 
disk space initially allocated to the file; the specified size should be an estimate of the average 
logical record size. The more accurate the estimate, the better the utilization of disk space. 

The physical record length is specified when the file is created and cannot be changed. 

It is often advantageous to store multiple logical records in a physical record. This is called 
blocking. 

Since disk transfer and latency times are relatively long, usually you should choose physical 
records large enough to Include several logical records. When a task first Issues a read request, 
DNOS actually reads an entire physical record Into memory. The physical record is stored in an 
area of memory called a blocking buffer. Only the part that corresponds to the requested logical 
record is passed to the requesting task. 

Subsequent read and write requests to a physical record in memory do not cause immediate disk 
access; instead, they reference the record image in memory. DNOS keeps an accessed physical 
record, which usually contains several logical records, in memory until the memory area is needed 
for other purposes or the file is closed. Blocking logical records and the deferred write capabilities 
can substantially improve system throughput, especially for sequential files. 
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If no physical record size is specified at creation time, DNOS assigns a default physical record 
size based on the file type. Sequential files and KIFs support variable-length records. Since DNOS 
can split logical records into two or more physical records in a sequential file, the physical record 
size can be smaller than the largest logical record. However, this results in inefficient processing 
of the file. 

2.1 .3.2 Saving Disk Space. Blank suppression and blank adjustment are two methods of saving 
disk space within a file by storing data in a more compact form. These methods apply only to KIFs 
and sequential files. While blank suppression always occurs on KIFs, it is optional on sequential 
files. 

Blank suppression replaces strings of blanks by a count of blanks when writing to disk and 
restores the blank string when reading from disk. In operation, blank suppression is transparent to 
the user. Usually, you should specify blank suppression for a source file, a listing file, or a text file, 
since these files tend to contain many blanks. However, keep in mind that blank suppression 
increases by one word the length of records containing no blanks. 

The second method, blank adjustment, applies to sequential files and I/O devices with variable 
record lengths. Blank adjustment truncates trailing blanks on output and restores them on input. 
To use this feature, you must set the blank adjust flag bit in an I/O SVC block. 

2.1. 3.3 Immediate Write. When DNOS writes a record of a blocked file, the record is placed in a 
blocking buffer in memory. The record in the buffer remains in memory as long as possible. Subse- 
::|uent read and write requests access the memory buffer and not the disk. The disk is accessed 
Dniy when DNOS needs the memory occupied by the blocking buffer or the file is closed. This 
belaying of disk writes increases system throughput. However, although the disk write is actually 
belayed, it is reported as being complete. Consequently, errors that occur during the write cycle 
are unexpected and in some situations may not be detected. DNOS supports an immediate-write 
aption, specified when a file is created, for files that cannot risk an undetected write error. 

The most common undetected error is disk failure. For example, you might update a record in a 
alock and be informed that the update has been successfully completed. However, when the 
alock is actually written to disk, possibly several minutes later, an I/O error might occur. This error 
s returned on the next call to the LUNO after the error. The error is returned even if the call is not a 
/Vrite operation. 

/Vhen deciding whether to include the immediate-write option, remember that undetected errors 
ire rare and that files (especially sequential files) with this option are less efficiently processed. 
Therefore, you should reserve this option for sensitive files that cannot risk loss of data. KIFs 
ilways include the immediate-write option. 
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2.1.3.4 Temporary Attribute. When you create a file, it usually remains in existence until you 
explicitly delete it. However, under DNOS you can also create temporary files as follows: 

• Create a temporary file using an Assign LUNO operation of the I/O SVC with the tempo- 
rary file bit set. In this case, the file remains in existence only as long as the LUNO is 
assigned. If you do not specify a name, DNOS assigns a unique temporary file name. 
However, the pathname portion of the I/O SVC block can indicate the disk volume on 
which the file is to be created. By using the Rename File operation of the I/O Operations 
SVC, you can explicitly name the file and specify it as permanent. Otherwise, it is 
deleted the first time its LUNO is released. 

• Create a temporary file using a Create File operation of the I/O Operations SVC with the 
temporary bit set and a pathname supplied. You can assign one or more LUNOs to the 
file using the pathname. The file remains in existence as long as at least one LUNO is 
assigned. When the last LUNO is released, the file is deleted. 

• Create a job-temporary file by using the Assign Logical Name SVC or the Assign Logical 
Name (ALN) SCI command followed by either the Create File (CF) command or the 
Assign Luno (AL) command. The discussion of name management in Section 1 
describes how to create a job-temporary fiie using these commands. 

2.1 .3.5 Expandability. When you create a file using the Create File operation of the I/O Opera- 
tions SVC, you can give the file a fixed size via the primary allocation parameter. Alternatively, you 
can create the file as expandable and give the primary allocation as its initial allocation. When the 
file exceeds its primary allocation, it is augmented with secondary allocations. The secondary 
allocation parameter is the size of the first secondary allocation. Subsequent secondary alloca- 
tions automatically and progressively increase in size over the previous allocation. Files add up to 
a maximum of 16 secondary allocations. 

2.1.3.6 End-of-File (EOF). An EOF is a logical position within a reiative record file or KIF. It is an 
actual record within sequential files. When read, it sets the EOF status bit. No data is transferred. 
The EOF status bit is bit 2 of the system flags. 
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Relative record files have one EOF that corresponds to tlie record following the highest-numbered 
written record. Sequential files can have more than onelEOF. A sequential file is analogous to a 
reel of magnetic tape that can contain several files sepa'rated by EOFs. A sequential file can con- 
sist of multiple data sets or subfiles marked by EOFs. A I^IF has a logical EOF that corresponds to 
the record following the record with the largest primary key. For a KIF, the EOF applies only to 
Read ASCII operations and Forward Space operations that access the file sequentially in primary 
key order. | 

i 

The internal representation of an EOF In a sequential file is a record of zero length. Either a Write 
EOF operation or a Close and Write EOF operation writes the EOF. Writing an EOF does not 
prevent writing more records to the file. i 


2.2 DISK ORGANIZATION 

I 

The organization of files on the disk is related to the folldwing: 

• Disk characteristics ' 

• Allocation of space on the disk i 

I 

• Physical organization of the disk 

2.2.1 Disk Characteristics 

I 

All tracks on disks are initialized in a one-sector-per-recdrd format. This record size is a character- 
istic of the type of disk and is not necessarily the physical record size for files to be created on the 
disk. 


Disks are logically divided into allocatable disk units (ADUs). An ADU is made up of one or more 
compiete sectors of the disk. The number of sectors per ADU varies according to the disk type 
(see Table 2-1) to provide a number of ADUs per disk lefts than 65,536. Each ADU on the disk can 
be addressed by a 16-bit word. ADU numbers start W;ith 0, the first ADU starting on track 0, 
sector 0. 
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Table 2-1. Format Information for Supported Disks 


Disk 

Type 

Available 
Space 
(M Bytes) 

No. 

ADUs 

No. 

Heads 

No. 

Cylinder 

Sec./ 

Track 

Sec./ 

ADU 

Bytes/ 

Sec. 

DS10 

4.7 

16,320 

2 

408 

20 

1 

288 

DS25 

22.3 

25,840 

5 

408 

38 

3 

288 

DS50 

44.6 

51,616 

5 

815 

38 

3 

288 

DS80 

62.7 

40,819 

5 

803 

61 

6 

256 

DS200 

169.5 

65,381 

19 

815 

38 

9 

288 

DS300 

238.3 

62,045 

19 

803 

61 

15 

256 

FD1000 

1.15 

4,004 

2 

77 

26 

1 

288 

GDI 400/32 
Removable 

13.5 

52,544 

1 

821 

64 

1 

256 

Fixed 

13.5 

52,544 

1 

821 

64 

1 

256 

GDI 400/96 
Removable 

13.5 

52,544 

1 

821 

64 

1 

256 

Fixed 

67.3 

43,786 

5 

821 

64 

6 

256 

WD500 

4.9 

19,200 

4 

150 

32 

1 

256 

WD500A 

17.0 

22,208 

3 

694 

32 

3 

256 

WD800-18 

18.5 

24,087 

3 

651 

37 

3 

256 

WD800-43 

43.2 

56,203 

7 

651 

37 

3 

256 

WD800A/38 

38.4 

50,105 

5 

911 

33 

3 

256 

WD800A/68 

69.2 

45,094 

9 

911 

33 

6 

256 

WD800A/114 

114.5 

49,720 

15 

904 

33 

9 

256 

WD900-138 

138.1 

59,928 

10 

805 

67 

9 

256 

WD900-138/2 

69.0 

44,946 

5 

805 

67 

6 

256 

WD900-425 

425.8 

61,600 

24 

693 

100 

27 

256 

WD900-425/2 

212.9 

55,440 

12 

693 

100 

15 

256 
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2.2.2 Disk Space Allocation to Files 

Disk space is allocated to files in multiples of ADUs. The ADD size, physical record length, and 
logical record length determine how efficiently disk space is utilized. Consider the following disk 
access characteristics: 

• Physical records start on sector boundaries. 

• Physical records that do not start on an ADU boundary cannot span an ADU boundary. 

• Logical records can span physical record boundaries in sequential files only. 

For efficient utilization of disk space by a file, the physical record size should be an integer mul- 
tiple of the sector size and an integer multiple or a factor of an ADU. If the file is a relative record 
file, the physical record size should be an integer multiple of the logical record size. 

An additional consideration in file definition is frequency of disk access. A disk access is required 
only when an I/O operation addresses a record that is not in the buffered physical record. As a 
rule, the physical record length should be at least three times the logical record length, allowing 
file management to buffer logical records. 

2.2.3 Physical Organization of a DNOS Disk 

Disks initialized under DNOS have the following physical layout: 

• Track 0/Sector 0 — Contains volume information such as the volume name and the loca- 
tion of VCATALOG. 

• Track 0/Sector 1 — Contains bad ADU list. 

• Remainder of track 0 — Contains bit maps indicating disk allocation information. The 
largest available block is recorded at the beginning. 

• Track 1 — Contains the disk program image loader and a copy of sectors 0 and 1 of 
track 0, used for recovery from a major disk failure. 

• Remaining tracks — Available for file allocation. 

• Reserved tracks — Contain alternate location of bad tracks on disks that support bad 
track mapping. 

2.2.3.1 Volume Information. The information stored in track 0, sector 0 of all disks initialized 
under DNOS is called volume information. Figure 2-1 shows the format of this 164-byte block of 
information. In this figure and those that follow, reserved fields are fields that DNOS does not cur- 
rently use but might use in the future. 
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0-7 

0-7 

Volume Name 

8-9 

8-9 

Number of ADUs 

10-11 

A-B 

Bit Map Sector No. 

No. OF Bit Maps 

12-13 

C-D 

Bytes per Physical Record 

14-15 

E-F 

Program Image Loader Track Number 

16-21 

10-15 

Reserved 

22-23 

16-17 

Number of 

Bad ADUs 

24-25 

18-19 

Program Image Loader Entry Point 

26-27 

1 A-IB 

Length of Program Image Loader 

28-35 

1C- 23 

Reserved 

36-37 

24-25 

Program Image Loader Track Number 

38-45 

26-2D 

Reserved 

46-53 

2E-35 

Primary System 

Image File Name 

54-61 

36-3D 

Secondary System Image File Name 

62-63 

3E-3F 

System Image 

Select Flag 

64-65 

40-41 

VCATALOG Starting ADU 

66-67 

42-43 

VCATALOG Physical Record Size 

68-69 

44-45 

Sectors/ADU 

70-73 

46-49 

Creation Date 

74-81 

4A-51 

Primary Program File Name 
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Figure 2-1. Volume Information Format (Sheet 1 of 2) 
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82-89 

52-59 

Secondary Program File Name 

90-91 

5A-5B 

Program File Select Flag 

92-99 

5C-63 

Primary Overlay File Name 

100-107 

64— 6B 

Secondary Overlay File Name 

108-109 

6C-6D 

Overlay File Select Flag 

110-117 

6E-75 

Primary System Loader File name 

1 1 8- 1 25 

76- 7D 

Secondary System Loader File name 

126-1 27 

7E-7F 

System Loader Select Flag 

128-135 

80-87 

Diagnostic File Name 

136-137 

88-89 

Diagnostic Select Flag 

138-143 

8A-8F 

Reserved 

144-151 

90-97 

Writable Control Storage File Name 

152-159 

98-9F 

WCS Secondary File 

160-161 

A0-A1 

Select Switch 

162-163 

A2-A3 

track 1 Select Flag 
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Figure 2-1 . Volume Information Format (Sheet 2 of 2) 
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The volume information shown in Figure 2-1 contains the following field descriptions: 

Byte Description 

0-7 Volume name, one to eight characters, blank filled to the right. 

8-9 Total number of ADUs contained in the volume. This field varies by disk 
type. 

10 The number of the sector in track 0 in which the first bit map resides. 

1 1 Total number of bit maps. 

12-13 The number of bytes per physical record (that is, sector) in track 0. This 
value is also disk dependent. 

14-15 The number of the track that contains the disk program image loader. 
This field is initialized to 1. 

16-21 Reserved. 

22 - 23 Total number of bad ADUs on the disk. 

24 - 25 Entry point address of the disk program image loader (initialized to > A4, 

the entry point of the loader when It is loaded at location > AO). 

26 - 27 Total byte length of the disk program image loader. 

28-35 Reserved. 

36-37 Second copy of the track that contains the disk program image ioader 
(initiaiized to 1). 

38-45 Reserved. 

46 - 53 Name of the primary system image file (one to eight characters). Zero at 
initialization. 

54 - 61 Name of the secondary system image file. Zero at initialization. 

62 - 63 System select flag. Zero at initialization. 

64 - 65 Number of the ADU In which the volume directory (VCATALOG) begins. 

66 - 67 Physical record size of the VCATALOG directory file. 

68 - 69 Number of sectors per ADU (disk dependent). 

70-73 Disk creation date. 
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NOTE 

The remaining fieids of the voiume information biock apply to sys- 
tem disks only. They are not given values when the disk is initial- 
ized. The Modify Volume Information (MVI) command writes the 
field values. 


Byte 

74-81 

82-89 

90-91 

92-99 

100-107 

108-109 

110-117 

118-125 

126-127 

128-135 

136-137 

138-143 

144-151 

152-159 

160-161 

162-163 


Description 

Primary system program file name 
Secondary system program file name 
System program file select flag 
Primary system overlay file name 
Secondary system overlay file name 
System overlay file select flag 
Primary system loader file name 
Secondary system loader file name 
System loader select flag 
Diagnostic file name 
Diagnostic select flag 
Reserved 

Writable control store (WCS) file name 
WCS secondary file 
Select switch 
Track 1 select flag 
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2.2.3.2 Bit Map. To identify which areas on the disk are allocated and which are free, DNOS 
maintains a bit map of allocated ADUs. The bit map is located in track 0 of each disk, starting at 
sector 2 and continuing through as many sectors as necessary. 

The bit map is divided into 128-word partial bit maps. Each partial bit map is located in a separate 
sector in track 0. The first word of each partial bit map contains the number of the ADU that begins 
the largest block of free disk space located in that part of the disk, which is mapped by the partial 
bit map. Each bit in the remaining 127 words represents an ADU. If the bit is zero, the ADU is free; 
if it is one, the ADU is allocated (or the ADU is on a bad track). Each partial bit map contains 127 
16-bit words of information and maps 2032 ADUs. Figure 2-2 shows the structure of a partial bit 
map. 


BYTE 0 


Relative ADD No. of Largest Available Block 


Partial Allocation Bit Map 

BIT = 1 MEANS 
ADU ALLOCATED 


2279388 


Figure 2-2. Partial Bit Map 

2.2.4 Displaying and Modifying Absolute Disk Addresses 

The following SCI commands are available to display or modify absolute disk addresses: 


Command 

Description 

SAD 

Show Absolute Disk 

SADU 

Show Allocatable Disk Unit 

MAD 

Modify Absolute Disk 

MADU 

Modify Allocatable Disk Unit 


2.3 DISK FILE STRUCTURES 

The structure of the directory file is a key to the organization of files on a disk. The following para- 
graphs describe the directory structure and the structure of each type of file that DNOS supports. 
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2.3.1 Directory File 

A directory contains information necessary to locate other files and descriptions of those files. 

Figure 2-3 illustrates the way in which all directories are connected in a network. The top of this 
network is the volume directory, called VCATALOG.. VCATALOG is created on each volume when 
the disk is initialized. It maintains information about directories, system files, and user files. 



Figure 2-3. Directory Structure 


2.3.1. 1 Directory File Characteristics. Directory files are unblocked relative record files con- 
sisting of one logical record per physical record. Figure 2-4 shows the file structure of a directory. 
Record 0 contains overhead information in the format shown in Figure 2-5. Each of the remaining 
records is of one of the following types: 

• File descriptor record (FDR) — Describes a file and its location on the disk. 

• Alias descriptor record (ADR) — Describes an alias for a file, includes the location of the 
file, and points to the FDR of the file. 
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• Channel descriptor record (CDR) — Describes a channel, specifies the program file of 
the owner task of the channel, and points to the FDR of the program file. 

• Key descriptor record (KDR) — Describes the keys defined for a KIF. An entry in the FDR 
of the KIF points to the KDR. Thus, each KIF requires two directory entries. 

Subsequent paragraphs describe the types of records in a directory. 

File names in a directory are hashed to a record number, 1 through N, where N is the last record in 
the directory. If a file name hashes to a record number and the record is unused, an FDR for the file 
being inserted is built in that record. If the record is already used, a linear search from the hashed 
record finds a free record. For KIFs, a linear search is performed from the FDR to locate an avail- 
able record for the key descriptor block. 


Reg. No. 



FDRs , ADRS; 
CDRs , AND KDRs 
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Figure 2-4. Directory Fiie Structure 
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Dec 

0-1 

HEX 

0-1 

Number of Records in Directory 

2-3 

2-3 

Number of Files in Directory 

4-5 

4-5 

Number of Available Records 

6-7 

6-7 

No. of Temp. Files Currently Defined 

8-15 

8-F 

File Name of Directory 

16-17 

10-11 

Level Number of Directory 

18-25 

12-19 

File Name of Parent 

26-63 

1A-3F 

Reserved 


227939 1 


Figure 2-5. Directory Overhead Record Format 


The directory overhead record, record 0 of all directories, contains the following: 

• Maximum number of records (entries) in the directory 

• Numberof currently defined files 

• Number of available records (entries) 

• File name of the directory 

• Level number of the directory in the disk hierarchy (VCATALOG is level 0) 

• File name of the parent directory 

2.3.1. 2 Fiie Descriptor Record (FDR). Each file cataloged under the directory is represented by 
an FDR, Figure 2-6 shows an FDR. 
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0-1 

0-1 

Hash Key Count 

2-3 

2-3 

Hash Key 

4-n 

4-B 

File Name 

12-15 

C-F 

Reserved 

16-17 

10-11 

Flags 

18-19 

12-13 

Physical Record Size 

20-21 

14-15 

Logical Record Size 

22-23 

16-17 

Primary Allocation Size 

24-25 

18-19 

Primary Allocation ADU 

26-27 

lA-lB 

Secondary Allocation Size 

28-29 

IC-ID 

Offset to Secondary Allocation Table 

30-31 

IE- IF 

Record Number of First Alias 

32-35 

20-23 

End of Medium Logical Record Number 

36-39 

24-27 

End of Medium Block Number 

40-41 

28-29 

End of Medium Offset 

42-45 

2A-2D 

Free Block Queue Head 

46-47 

2E-2F 

Block No. of B-Tree Root (Primary Key) 

48-49 

30-31 

Block Number of First Data Blocks 

50-51 

32-33 

Total Number of Data Blocks 

52-53 

34-35 

Record Number of Key Descriptors 

54-59 

36-3B 

Date and Time of Last Update 

60-65 

3C-41 

Date and Time File Creation 

66 

42 

ADUs /Block 

Blocks/ A DU 


KIF 
> Files 
Only 
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Figure 2-6. FDR Format (Sheet 1 of 2) 
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Dec Hex 

68-69 44-45 

70-71 46-47 

72-73 48-49 

132-133 84-85 

2279392 ( 2 / 2 ) 

Figure 2-6. FDR Format (Sheet 2 of 2) 

The FDR shown in Figure 2-6 contains the following information: 

Byte Description 

0-1 Hash key count. The number of records in the directory that 

hashed to this record number. 

2-3 Hash key. The result of the hash algorithm for the file name in this 

FDR. The hash value might not be the number of this record. When 
the hash value record has already been written, DNOS searches 
linearly for an unused record. 

4-11 File name (eight characters). 

12-15 Reserved. 

16-17 File usage flags. 

18-19 Physical record size in bytes. Must be an even number. 

20-21 Logical record size in bytes. Must be an even number if the file is 

unblocked. 

22 - 23 Primary allocation size, in ADUs. 

24 - 25 Primary allocation starting ADU number (starting disk address). 

26 - 27 Secondary allocation size In ADUs. 

28-29 Offset into this FDR of the secondary allocation table. When the 

file is not expandable or before a secondary allocation has been 
made, the field contains 0. 
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Byte 

30-31 

32-35 

36-39 

40-41 

42-45 

46-47 

48-49 

50-51 

52-53 

54-59 

60-65 

66 

67 

68-69 

70-133 


Description 

Record number of the ADR for the file’s first alias or of the CDR. 
Contains zero when no alias is defined and no CDR exists. 

Logical record number of the end-of-medium (EOM). The EOM is 
the end of the last space allocated to the file. 

The logical block (physical record) number of the EOM. 

The offset into the EOM block of the logical record following the 
EOM record. 

Block number of the first block in a queue of KIF blocks with avail- 
able space. Each block points to the next block in the queue. A 
block is a physical record of the file. This number is used only for 
KIFs. 

The block number of the B-tree root block of the primary key. The 
block following this is the KIF root block for key 2, and so on. This 
field is also the total number of blocks that can be used for 
logging. 

The block number of the first KIF data block. 

The total number of data blocks in the KIF. 

Record number of the KDR. 

Date of the last update to the file. 

Creation date of the file. 

The number of ADUs per physical record. 

The number of physical records per ADU. 

The minimum size for a KIF logical record; the KIF must contain all 
of the keys defined. 

The secondary allocation table, which contains two-word entries. 
The first word of an entry contains the size, in ADUs, of the first 
secondary allocation. The second word contains the starting ADU 
of the allocation. The table can contain as many as 16 entries and 
is used only when the file expands. Unused fields contain zeros. 
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The file usage flags in bytes 16 and 17 have the following meanings: 


2279394 


0-1 

00 

1 

CM 

4 

5-6 

7 

8 

9 

10 

1 1 

1 2 

13-14 

15 


Bit(s) Meaning 

0-1 File usage, as follows: 

00 — No special usage 

01 — Directory file 

10 — Program file 

11 — Image file 

2-3 Format, as follows: 

00 — Binary 

01 — Blank compressed 

4 Allocation type, as follows: 

1 — Expandable 

0 — Primary allocation only 

5-6 File type, as follows: 

01 — Sequential 

10 — Relative record 

11 — Key indexed 

7 Write protected, as follows: 

1 — Write protected 

0 — Not write protected 

8 Delete protected, as follows: 

1 — Delete protected 

0 — Not delete protected 

9 Temporary file, as follows: 

1 — Temporary file 

0 — Not a temporary file 

10 Blocked, as follows: 

1 — Unblocked 
0 — Blocked 
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Bit(s) Meaning 

1 1 Reserved 

12 Immediate write, as follows: 

1 — Immediate write mode 
0 — Deferred write mode 

13-14 Reserved 

15 Reserved 

2.3.1. 3 Alias Descriptor Record (ADR). An alias is an alternate name for a file. A directory con- 
tains an ADR for each alias of any file in the directory. The assignment of a record number for an 
ADR Is similar to the assignment of a record number for an FDR. The alias is hashed to derive a 
record number. When the record is available, the ADR is written to that record. Otherwise, DNOS 
searches the file linearly from that record to locate an available record; DNOS writes the ADR in 
the first available record. 

The number of aliases a file can have is limited only by the number of empty records available in 
the directory. An ADR Implements each alias. The ADRs for the aliases of a file are linked to the 
FDR of the file and to each other. 

The program file of a task that is the owner task of an IPC channel has one or more CDRs linked to 
the FDR of the file along with any ADRs associated with the file. 

Figure 2-7 shows the format of the ADR, which is similar to that of the FDR. It includes 34 bytes. A 
flag Identifies the record as an ADR. A field of the ADR contains the record number of the FDR for 
the file. Another field contains the record number of the next ADR or CDR linked to the FDR. When 
no record is linked to the ADR (that is, this ADR is the end of the linked list), this field contains 0. 


Dec Hex 

0-1 0-1 

2-3 2-3 

4-11 4-B 

12-15 C-F 

16-17 10-11 

18-29 12-lD 

30-31 IE- IF 

32-33 20-21 

2279393 


Figure 2-7. ADR Format 
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The ADR shown in Figure 2-7 contains the following information: 

Byte Description 

0-1 Hash key count. The number of records in the directory that hashed 

to this record number. 

2-3 Hash key. The resuit of the hash algorithm for the aiias in this ADR. 

The hash vaiue might not be the number of this record. When the 
hash value record has already been written, DNOS searches iinearly 
for an unused record. 

4-11 Alias. The aiias in this item is an alternate name for the file (that is, 

a secondary name by which a previously defined fiie is aiso known). 

The primary name for a file is supplied in the FDR. Secondary 
names are documented in the ADR. 

12-15 Reserved. 

16-17 File usage flags. These apply to the file and are identical to those in 

the FDR except that bit 1 1 is set to identify this record as an ADR. 

18-29 Reserved. 

30-31 Record number of next alias. This is a pointer chaining forward to 

another ADR for the same file, if one exists. If one does not exist, 
this value is 0. 

32-33 Record number of actual file. A pointer to the directory file record 

that contains the fiie descriptor for this particular file. 

The file usage flags in bytes 16 and 17 appiy to the file described in the FDR at the record in bytes 
30 and 31. The flags have the following meanings: 
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0-1 

2-3 

4 

5-6 

7 

8 

9 

1 0 

1 1 

12 

13-14 

15 


Bit(s) Meaning 

0-1 File usage, as follows: 

00 — No special usage 

01 — Directory file 

10 — Program file 

11 — Image file 

2-3 Format, as follows: 

00 — Binary 

01 — Blank compressed 
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Bit(s) Meaning 

4 Allocation type, as follows: 

1 — Expandable 

0 — Primary allocation only 

5-6 File type, as follows: 

01 — Sequential 

10 — Relative record 

11 — Key Indexed 

7 Write protected, as follows: 

1 — Write protected 

0 — Not write protected 

8 Delete protected, as follows: 

1 — Delete protected 

0 — Not delete protected 

9 Temporary file, as follows: 

1 — Temporary file 

0 — Not a temporary file 

10 Blocked, as follows: 

1 — Unblocked 

0 — Blocked 

11 ADR; set to 1. 

12 Immediate write, as follows: 

1 — Immediate write mode 
0 — Deferred write mode 

13-14 Reserved 

15 Reserved; set to 0. 

2.3.1.4 Channel Descriptor Record (CDR). The CDR describes an IPC channel. It is associated 
with the program file of the channel owner task and is linked to the FDR of the program file along 
with any aliases for the file. 

The allocation of a record in the directory for a CDR is similar to the allocation of an ADR. The 
channel name is hashed and the result is used as a record number. When the record is already- 
occupied, the next available record is used. 

Figure 2-8 shows the format of the CDR. 
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Dec Hex 

0-1 0-1 

2-3 2-3 

4-n 4-B 

12-15 C-F 

16-17 10-11 

18 12 

20 14 

22-23 16-17 

24- 29 1 8- ID 

30-31 IE- IF 

32-33 20-21 

34-143 22- 8F 

144 90 

146-255 92-FF 

2279396 

Figure 2-8. CDR Format 

The CDR shown in Figure 2-8 contains the following information: 

Byte Description 

0-1 Hash key count. The number of records in the directory that hashed 

to this record number. 

2-3 Hash key. The result of the hash algorithm for the channel number. 

The hash value might not be the number of this record. When the 
hash value record has already been written, DNOS searches linearly 
for an unused record. 

4-11 Channel name (eight characters). 

12-15 Reserved. 

16-17 File usage flags; bit 15, the channel descriptor flag, is set to one. 
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Byte 

18 

19 

20 


21 

22-23 

24-29 

30-31 

32-33 

34-143 

144 

145-255 


Description 

Channel flags. These flags define the channel. 

Installed ID of owner task. 

Default resource type. The resource type of the channel as it 
appears to the requesting task. The significance of the contents of 
this byte depends on the resource type flag (as described in a sub- 
sequent paragraph). 

Resource type flags. 

Maximum length for messages that the channel transfers. 

Reserved. 

Record number of next CDR or ADR. The record number of the next 
record in the linked list of CDRs and ADRs. This field contains 0 
when this CDR is the last record in the list. 

Record number of FDR of the channel owner task program file. 

Reserved. 

User ID. The user ID of the user who created the IPC channel. 
Reserved. 


Of the file usage flags in bytes 16 and 17, bits 0 through 14 are reserved. Oniy bit 15, the CDR flag, 
applies. The flags have the following meanings: 
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0-1 

2-3 

4 

5-6 

7 

8 

9 

10 

1 1 

1 2 

13-14 

15 


Bit(s) 

Meaning 

0-14 

Reserved. 

15 

CDR, as follows: 


1 — Record is a CDR 


0 — Record is not a CDR 


2270510-9701 


2-27 




Disk and File Organization 


The channel flags, byte 18, define the channel attributes as follows; 
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0-1 

2 

3 

4 

5-7 


Bit(s) Meaning 

0-1 Scope of channel, as follows: 

00 — Task local 

01 — Job local 
10 — Global 

2 Shared, as follows: 

1 — Channel is shared. 

0 — Channel is not shared. 

3 Symmetric, as follows: 

1 — Symmetric channel 

0 — Master/slave channel 

4 Assign, as follows: 

1 — Channel owner processes assign LUNO. 

0 — Channel owner does not process assign LUNO. 

5 Abort, as follows: 

1 — Channel owner processes abort request. 

0 — Channel owner does not process abort request. 

6 I/O utility, as follows: 

1 — Channel owner processes I/O utility request. 

0 — Channel owner does not process I/O utility request. 

7 Reserved. 
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When the device resource type flag (bit 6, byte 21) is set, the default resource type (byte 20) has the 
following significance: 

0 — Dummy device 

1 — Special device 

2 — 743 keyboard send/receive (KSR) 

3 — 733 automatic send/receive (ASR) 

4 — 733 cassette drive 

5 — Reserved 

6 — Single-sided diskette drive 

7 — Diskdrive 

8 — Magnetic tape drive 

9 — Teleprinter device (TPD) 

10 — 911 VDT 

11 — Serial printer 

12 — Parallel printer 

13 — Four-channel communication controller (FCCC) 

14 — Communication interface module (CIM) 

15 — Industrial device 

16 — Card reader 

17 — 940 VDT 

18 — 931 VDT 

19 — Reserved 

20 — Bit-oriented/character-oriented asynchronous 

interface module (BCAIM) 

When the file resource flag (bit 7, byte 21) is set, the default resource type (byte 20) has the follow- 
ing significance: 


Value 


Device 


0 Reserved 

1 Sequential file 

2 Relative record file 

4 Directory file 

5 Program file 

6 Image file 
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The resource type flags in byte 21 define the default resource type in byte 20. The flags are as 
follows: 


2279399 


0-4 

5 

6 

3 


Bit(s) Meaning 

0-4 Reserved. 

5 Channel resource flag, as follows: 

1 — Default resource is an IPC channel. Byte 20 con- 
tains a channel resource type. 

0 — Default resource is not an IPC channel. 

6 Device resource flag, as follows: 

1 — Default resource is a device. Byte 20 contains a 

device resource type. 

0 — Default resource Is not a device. 

7 File resource flag, as follows: 

1 — Default resource is a file. Byte 20 contains a file 
resource type. 

0 — Default resource is not a file. 

When the channel resource type flag (bit 5, byte 21) is set, the default resource type (byte 20) 
should contain 0 for a symmetric channel. 

2.3.1.5 Key Descriptor Record (KDR). If the file being inserted is a KIF, the KDR requires 
another directory record. DNOS locates this record by searching linearly from the FDR of the file. 
The KDR is inserted in the first available directory record following the FDR. 

A KIF has a primary key and can have as many as 13 secondary keys. A KDR describes the keys 
that access records in the file. Figure 2-9 shows the format of a KDR. 
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Figure 2-9. KDR Format 


The KDR shown in Figure 2-9 contains the following information: 

Byte Description 

0-1 Hash key count. The number of records in the directory that hashed to 
this record number. The KDR is not hashed. When this value is greater 
than 0, an FDR, ADR, or CDR has been written in the next available 
record because this record is occupied. 

2-3 Hash key. This field corresponds to the hash key field of other direc- 
tory records and contains - 3, indicating that this is a KDR. 

4-5 Reserved. 

6-7 The number of keys defined for this KIF. A maximum of 14 keys are 
available for any KIF. One key, the primary key, is required. Keys 2 
through 14 are optional secondary keys. 

8 Primary key flags. 

9 The key length, in bytes (characters), for the primary key. 

10-11 The byte number of the first character of the key within the KIF data 

record. 

12-63 Data for the secondary keys, if any. Four bytes in the format shown 
for the primary key (that is, key flags, key length, and key offset) are 
supplied for each secondary key. 
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The key flags are defined as follows: 


2279401 


0-3 

4 

5 

6 

3 


Bit(s) 


Meaning 


0-3 Reserved. 

4 Sequential placement flag. Applies only to primary key, as follows: 

1 — Created by system using sequential placement scheme. 

0 — Created by system using hash placement scheme. 

5 Value present flag, as follows: 

1 — Value need not always be present. (Valid only for secondary 

keys.) 

0 — Value must always be present. 

6 Sequential commands flag, as follows: 

1 — Sequential commands are desired. 

0 — Sequential commands are not desired. 

7 Duplicates flag, as follows: 

1 — Duplicate vaiues are allowed for this key. 

0 — Unique vaiues are required for this key. 

2.3.1.6 Example of a Dump Directory. Figure 2-10 shows a dump of the directory file .JB.DIR. 
The directory contains a sequential file (.JB.DIR.SEQ), an image file (.JB.DIR.IMAG), a program file 
(.JB.DIR. PROG), and a KIF (.JB.DIR.KEYFILE). The directory also contains an alias for the KIF 
(.JB.DIR.KEYFILE) and the KDR for the KIF. The directory was created to have seven entries in 
addition to record 0 (the directory overhead record). 

2.3.2 Sequential Files 

Sequential files support variable-length logical records. Logical records can span physical record 
boundaries regardless of ADU boundaries. When a logical record spans a physical record bound- 
ary, it is divided into partial records in separate physical records. The first word of each physical 
record has two flags, which indicate the following: 

• Whether the first logical record is continued from the preceding physicai record 

• Whether the last logical record is continued to the foilowing physical record 
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/ 


FILE ACCESS NAME: .JB.DIR 
RECCiRD : 000000 

0000 0007 0004 0001 0000 4449 5220 2020 2020 

0010 0002 4A42 2020 2020 2020 0300 0000 0000 

SAME 

OOFE 0000 
R E C 0 R 0 : 0 0 0 0 0 1 

0000 0000 0005 5345 5120 2020 2020 0000 0000 

0010 OAOO 0300 0050 0001 068A 0001 0000 0000 

SAME 

0036 07BD OlOE 9121 07BD OlOE 91F1 0101 0000 
SAME 

0090 4A4F 4E20 2020 2020 0000 0000 0000 0000 
SAME 

OOFE 0000 
RECORD: 000002 

0000 0001 0002 5052 4F47 2020 202:0 0000 0000 

0010 SC20 0120 0120 0011 4CAE 0001 0000 0000 

0020 0000 0033 0000 0033 0000 0000 0000 0000 

0030 0000 0000 0000 07BD OlOE 91 OB 07 BD OlOE 

0040 91EA 0103 0000 0000 0000 0000 0000 0000 

SAME 

0090 4A4F 4E20 2020 2020 0000 0000 0000 0000 
SAME 

OOFE 0000 
RECORD: 000003 

0000 0000 0000 0000 0000 0000 0000 0000 0000 
SAME 

OOFE 0000 
R E C 0 R D : 0 0 0 0 0 4 

0000 0003 0004 4B45 5920 2020 2020 0000 0000 

0010 1E08 0300 00 1C 002 A 4CBF 0001 0000 0006 

0020 0000 0000 0000 0029 0001 0000 0029 0027 

0030 0029 0059 0005 07BD OlOE 9184 07 BD OlOE 

0040 ■■5'IEE 0101 00 ID 0000 0000 0000 0000 0000 

SAME 

0090 4A4F 4E20 2020 2020 0000 0000 0000 0000 
SANE 

OOFE 0000 
RECORD: 000005 

0000 0001 FTFD 0059 0002 080D 0000 0014 0009 

0010 0000 0000 0000 0000 0000 0000 0000 0000 

SAME 

OOFE 0000 
R E C 0 R D : 0 0 0 0 0 6 

0000 0000 0004 4B45 5946 494C 4520 0000 0000 

0010 1E18 0000 0000 0000 0000 0000 0000 0000 

0020 0004 0000 0000 0000 0000 0000 0000 0000 

SAME 

C)OFE 0000 
I'^ECCRD : 000007 

0000 0000 0004 494D 4147 2020 2020 0000 0000 

0010 C420 0120 0120 0011 4CE9 0001 0000 0000 

ISA ME 

0036 07BD OlOE 9118 07BD OlOE 91F0 0103 0000 
SAME 

0090 4A4F 4E20 2020 2020 0000 0000 0000 0000 
SAME 

OOFE 0000 



Figure 2-10. Dump of a Directory Fiie 
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The flag bits, when set to 1, have the following meanings: 

Bit Meaning 

0 First logical record in this physical record is continued from the preceding 
record. 

1 Last logical record In this physical record continues in the next record. 

Figure 2-11 shows the format of a sequential file. Each logical record or partial record is preceded 
by a header word and followed by a trailer word. The header and trailer words contain the number 
of bytes of user data. An EOF is signified by a zero-length record (zero header and trailer). 

When a record ends with only one or two words remaining in the physical block, there is no room 
for another partial record (header/data/trailer). In this special case, the next record begins in the 
following block; the last word of the physical record is effectively a physical record trailer. It con- 
tains the number in the last trailer plus the number of unused bytes (two or four). 

Logical records of a sequential file can be blank suppressed. (The sequential file is created blank 
suppressed.) In blank-suppressed files, words that contain two blanks are removed. A blank- 
suppressed logical record has the following format: 

• Header word 

• Byte containing a count of words of blanks 

• Byte containing a count of words that contain at least one nonblank character 

• Data characters 

• Repetitions of items 2 through 4 

• Trailer word 
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Dec Hex 


0 

0 

2 

2 

4 

4 

to 

A 

12 

C 

14 

E 

16 

10 

28 

1C 

30 

IE 

32 

20 

34 

22 

42 

2A 

44 

2C 


Physical Record 0 



(Partial) 


A 


Record 2 Trailer 


2279402 ( 1 / 2 ) 


Figure 2-11. Sequential File Format (Sheet 1 of 2) 
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Dec Hex 
0 0 

2 2 

4 4 

8 8 
10 A 
12 C 
14 E 

22 16 
24 18 

26 lA 
28 1C 

36 24 

38 26 

40 28 

42 2A 
44 2C 


Physical Record 1 


Logical Record 2 Data 


Flags 

Record 2 Header 





2279402 ( 2 / 2 ) 


Figure 2-1 1 . Sequential File Format (Sheet 2 of 2) 
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Figure 2-12 shows a blank-suppressed record. Notice that items 2 and 3 precede each group of 
characters (Item 4) and that the number of words in item 3 is the length (in words) of item 4. In 
Figure 2-12, counts are hexadecimal, and hexadecimal ASCII representations are shown for 
characters. 


Input Record: 
Column: 


2279403 


0 0 112 2 3 3 8 

• • • 

15050505 0 

FIRST LAST AGE (Columns 33- 

80 blank) 


2.3.3 Relative Record Files 

A relative record file is a file in which each logical record can be randomly accessed by its unique 
record number. All records in a relative record file are of the same length. Relative record files can 
be unblocked or blocked: 

• Unblocked — The logical record size is greater than half of the physical record size. 

• Blocked — The logical record size is less than or equal to half of the physical record 
size. 

2.3.3.1 Unbiocked Reiative Record Fiies. Each logical record of a relative record file occupies 
one physical record of the file. A physical record should be any integral multiple of contiguous 
sectors. File accesses require reading or writing all sectors of a physical record. One disk access 
can read multiple contiguous sectors; Records read from unblocked relative record files are trans- 
ferred directly from the disk to the user buffer without intermediate system buffering. When the 
user specifies a particular record of the file, the record number is converted to an absolute ADU 
number and a sector offset within the ADU. The absolute disk address is then passed to the disk 
device service routine (DSR) to perform the actual data transfer. The disk DSR converts the ADU 
and relative sector to the physical track and sector disk address that the disk controller hardware 
requires. 
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r 


1 


Preceding Logical Records 
(If Any) 


0016 

00 

03 

46 

49 

52 

53 

54 

20 

04 

02 

4C 

41 

53 

54 

05 

02 

20 

41 

47 

45 

18 

00 

0016 


Succeeding Logical Records 
(If Any) 


J 


Record Header 

0 WORDS BLANKS, 3 WORDS DATA 

F I 
R S 

T BLANK 

4 WORDS BLANKS , 2 WORDS DATA 
L A 

5 T 

5 WORDS BLANKS, 2 WORDS DATA 
BLANK A 
G E 

24 WORDS BLANKS, 0 WORDS DATA 
Record Trailer 


2279404 


Figure 2-12. Blank-Suppressed Record 
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Each physical record must begin on a sector boundary. A physical record that begins on a sector 
boundary that is not also an ADU boundary cannot span the ADU boundary. The disk format for 
unblocked relative record files is as follows. In the first format, the record is larger than the ADU; 
in the second format, the record is smaller than the ADU. 

Unblocked Relative Record File 

Record Size > ADU Size 


RECORD 


ALL DATA 


ALL DATA 


ALL DATA 


UNUSED 


/\ 

/\ 


/ 

v 


A/ 


\r 



ADU 


ADU 


ADU 



2279405 


Record Size < ADU Size 


Physical 



^ 

Logical 

A 


/ \ 


all data 



ALL DATA 


ALL DATA 


FIRST RECORD 


SECOND RECORD 


ADU 


THIRD RECORD 


UNUSED 


2279406 
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2.3.3.2 Blocked Relative Record Files. These files are similar to unblocked relative record files 
except that multiple logical records can be stored In each physical record. Logical records cannot 
span physical records. Records are transferred via intermediate blocking buffers that are in the 
general pool of user space. The disk format for blocked relative record files is as follows: 


Blocked Relative Record File 


PHYSICAL RECORD 1 


PHYSICAL RECORD 2 


REC 1 

REC 2 

REC 3 

REC 4 

■ 


REC 5 

REC 6 

REC 7 

REC 8 

■ 



4 LOGICAL RECORDS 


UNUSED 


4 LOGICAL RECORDS 


ADU 


UNUSED 


2279407 


2.3.4 Key Indexed Files (KIFs) 

A KIF is a file in which you can access records by the value of a character string called a key. Each 
KIF can have as many as 14 keys, with access through each key independent of the other keys. 

Each entry of data made to the file is called a record. DNOS reads the records of other file types by 
identifying their positions in the file. In contrast, DNOS reads the records of KIFs by identifying a 
portion of the content of the record. 

2.3.4.1 KIF Keys. A character field used to identify a record is called a key. A key is defined at 
the file level and applies to every record in the file. It is a static set of values that cannot be 
changed except by reconstructing the file. A KIF must have at least one key. KIF key fields are 
defined when the file is created and can be from 1 to IQO characters long. 

The first key defined is the primary key; the others are defined as secondary keys. The primary key 
need not be in the first portion of a record; also, secondary key fields can physically precede the 
primary key within a record. 

When you define a key, you can specify the following: 

• Whether the key permits duplicates 

• Whether the key is modifiable 

If the value of a key must be unique throughout an entire file, the key must not permit duplicates. 
This prevents a record from being inserted into the file if the record has the same key value as a 
record already in the file. For example, keys such as employee numbers and social security num- 
bers should not be duplicatable, while keys such as names and salaries should permit duplicates. 

If a key is modifiable, you can change its value after a record with that key value has been inserted 
into the file. A key containing a person’s salary should be modifiable, while a key containing the 
person’s social security number should not be modifiable. If a record with a nonmodifiable key 
contains incorrect data, the only way to correct it is to delete and reenter the record. The primary 
key cannot be modifiable. 
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2.3.4.2 KIF Records. As you enter records into a KIF, they are logically sorted by key value. If 
more than one record has the same key value, -they are sorted in the order they were entered. 

The records of a KIF can be read either randomly or sequentially. When the records are read ran- 
domly, a key number and key value must be given for each Read operation. When the file is read 
sequentiaily, a key number and key value Is supplied for the first read. The sorted order of that key 
determines the sequence of logical records returned by subsequent Read operations. The 
operation requests the next record either in forward or backward order. 

2.3.4.3 KIF Key and Record Example. Since a key is defined for each record in the KIF, the 
records should contain related information, at least for the key portion. For example, related infor- 
mation could be a number (social security or employee number) or a name. The following example 
illustrates a KIF record and the keys the record contains: 


1-9 

0 

CM 

1 

o 

21-30 

31-40 

41-46 

47 

48-52 

123456789 

1 DOE 1 

JOHN 

ANDREW 1 

004442 


02400 


2279408 


Key 

Columns 

Definitions 

1 

41-46 

Employee number 

2 

01-09 

Social security number 

3 

10-20 

Last name 

4 

21-30 

First name 

5 

31-40 

Middle name 

6 

10-40 

Full name 

7 

47-47 

Sex 

8 

48-52 

Monthly salary 


The record is 52 characters long and contains 7 fields. Since the name fields are used in more than 
one key, the record has 8 keys. Although this example does not include characters between keys, 
you have the option of entering blanks or other data between keys. Also, in the example every 
column is defined to be in at least one key. This is not required. Quite often only a small portion of 
the record is defined to be part of a key, while the rest of the record contains data. The only require- 
ments are that a primary key must be included and that no key can be longer than 100 characters. 
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Since the primary key does not have to be in any particular position or have any qualities different 
from the other keys, you cannot determine which key is the primary key by looking at a KIF record. 
Instead, you can determine the primary key by entering a Map Key Indexed File (MKF) command. 
The primary key is identified as key number 1, as in the following example: 


Key 

Start 

Column 

Length 

Modifiable* 

Duplicates 

Allowed* 

1 

41 

6 

N 

N 

2 

1 

9 

N 

N 

3 

10 

11 

Y 

Y 

4 

21 

10 

Y 

Y 

5 

31 

10 

Y 

Y 

6 

10 

31 

Y 

Y 

7 

47 

1 

N 

Y 

8 

48 

5 

Y 

Y 


Note: 

* Y indicates yes and N indicates no. 

2.3.4.4 Structure of KIFs. The structure of a KIF consists of the prelogging area, the B-tree 
blocks, the data blocks, and the free chain blocks. A block is another term for a physical record. 
Figure 2-13 shows the structure of the KIF before any records have been inserted. The allocation 
for the file includes an area reserved for data and the B-tree area. The EOM is at the beginning of 
that area. As records are inserted, B-tree blocks and data blocks are added, moving the EOM 
toward the end of the allocation. The EOM indicates the current extent of the file. (KIFs are 
expandable.) 

You can also compress these files. When you copy KIFs using the Copy Directory (CD) command 
or the Restore Directory (RD) command, you can compress the size to the EOM with the compress 
(CMP) option. 
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2279409 


Figure 2*13. KIF Structure 


Prelog Area 

The first (18 x K) + 3 physical records, where K is the number of keys defined for the file, are 
the KIF prelog blocks. Any physical record modified is first copied to a prelog block to pre- 
vent data loss in case of a fatal error during the data transfer. If a fatal error occurs, the 
logged image is written back into the original record on the next open of the file. 

B-Tree 

The next K physical records are the root nodes of the B-trees. Every defined key has a B-tree 
(up to 14 B-trees). 

Free Chain 

One block is created initiaily adjacent to the B-tree roots to contain the chain of free blocks. 
The block is accessed using a pointer in the file control block (FCB). The FCB is a memory- 
resident data structure of the file descriptor block. 

When B-tree blocks become empty, the freed blocks are placed on the free chain. When a 
record is deleted from a data block, the data block Is placed on the free chain. When a record 
is inserted into the file, it is placed In a block on the free chain. 

Data Blocks 

Data blocks contain the logical records of the file. All user data (logical records) is blank 
suppressed when stored in data blocks. The following paragraphs describe the structure of 
B-trees and data blocks. 
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Sequential Record Placement When you insert data records into a KIF, the data records are 
piaced in the data area sequentiaiiy. When you delete records from a file, available blocks are 
placed on the free chain to utilize available space. The KIF uses the available space on the free 
chain before using any space after the EOM. Figure 2-14 shows sequential record 
placement. 



PRE LOGGING 

Area 


B-Tree 


Roots 


Free Chain 


Data 

► 


— * 

Free 


Data 


B-Tree 

Uo 

Free 


Data 


EOM 


End Of 


Allocation 


Data and B-Tree Area 


2279410 


Figure 2-14. Sequential Record Placement Method 
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B-Trees. A B-tree is a balanced tree. It has multiple branches per node, and all leaf nodes are at 
the same level. DNOS B-trees can include as many as nine levels. 

Each node of a B-tree occupies one physical record of a KIF and is called a B-tree block. The root 
node is initialized when the file is created, but all other nodes are created as records are added. 
Each B-tree block contains a few words of overhead and several pointer/key value pairs. 
Figure 2-15 shows the format of a B-tree block. 

Dec Hex 
0-3 0-3 

4-5 4-5 

6-7 6-7 

8- I t 8-B 

1 2- 1 5 C- F 

16 10 
18 12 

20-23 14-17 

24-25 18-19 

26- n lA-n 


n = 26 ( > 1 A ) + LENGTH OF KEY 

22794 1 T 

Figure 2-15. B-Tree Block Format 
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The fields of the B-tree block are as follows; 

Byte Description 

0-3 Physical record number of this B-tree block. Used for unlogging. 

4-5 Log number that file management assigns when this block is logged. 

6-7 Number of available bytes remaining in this B-tree block. 

8-11 Preceding node on the same level; zero if leftmost. 

12-15 Next node on the same level; zero if rightmost. 

16 Number of pointer/value pairs in the B-tree block. 

17 Flags, as follows: 

Bits 0 - 6 — Reserved 

Bit 7 — Set to 1 for leaf node; otherwise, set to zero 

18 Sequential Input position. 

19 Sequential input counter. 

20-23 Physical record number of the next lower node if this is not a leaf 

node. If it is a leaf node, physical record number of the data block 
containing the logical record associated with the key value. 

24-25 For a leaf node, the ID of the logical record within the data block. 
Otherwise, this word is reserved. 

26 - n The actual key characters. 

The remainder of the B-tree block contains more pointer/value pairs, each containing a physical 
record number and a key value (as in the pair that begins at byte 20). These entries in a B-tree block 
are kept sorted in increasing order of key value. The smallest key value is the first entry. 

The log number in the B-tree block and in data blocks is a number that file management assigns 
when any operation that modifies any block In the file Is performed. The same log number is 
placed in all blocks being modified during the operation. This is done as the blocks are logged 
(that is, copied into the prelog area). If you need to restore the file due to unsuccessful completion 
of the operation, the records in the prelog area with the log number of the operation are unlogged 
(copied back into the file). 
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The sequential input position, byte 18, and the sequential input counter, byte 19, require some 
explanation. When the B-tree block is created, byte 18 is set to 0 and byte 19 to the number of 
pointer/value pairs available plus 1. After the first insert, byte 18 Is set to the number of keys in the 
block greater than the inserted key, and the value in byte 19 decreases by 1. Subsequent inserts 
decrease the value in byte 19 by 1 if the number of keys in the block greater than the inserted key 
equals the value in byte 18. If byte 19 equals 1 when the B-tree block is about to split, the ratio of 
the split will be 90/10 instead of 50/50. The 90/10 ratio indicates that the top 90 percent of the keys 
are placed in one block and the remaining 10 percent in another. 

If the block is not a leaf node, each pointer field points to the root of the subtree that contains all 
key values less than or equal to the key value associated with the pointer. That is, the highest 
key value contained in the subtree is the key value associated with the pointer, as shown in 
Figure 2-16. 

Figure 2-16 shows the development of the B-tree for a key of an example file. The key is two char- 
acters long, and each node has three pointer/value pairs. When the file is created, the root node 
contains one pointer/value pair, containing > FFFF, the maximum value of the key. The first opera- 
tion inserts a record with a key of AO, resulting in two pointer/value pairs in the root node. Inserting 
another record, key MO, fills the root node. 

The next record to be inserted has a key value of BO. The root node is split, producing a second 
level in the B-tree. For purposes of this example, all splits are 50/50. The new level contains two 
nodes, and the root node contains pointers to these nodes. The root node now contains keys BO 
and > FFFF. The left node at the new level contains keys AO and BO, and the right node contains 
keys MO and > FFFF. Inserting a record with a key of A1 fills the left node at the bottom (leaf node) 
level. 

When the record with a key of A2 is inserted, the left node splits, resulting in three leaf nodes. The 
nodes contain keys AO and A1, A2 and BO, and MO and > FFFF, from left to right. When the record 
with key A3 is inserted, it fills the center leaf node. 

Inserting the record with a key of A4 again forces a new level. All nodes except the left and right 
leaf nodes are modified. The root node now contains keys A3 and > FFFF. The second level con- 
sists of two nodes. The left node contains keys A1 and A3, and the right node contains keys BO 
and > FFFF. The new level contains four nodes with keys AO and A1, A2 and A3, A4 and BO, and MO 
and > FFFF, from left to right. 
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CREATION 


INSERT AO 


INSERT MO 


INSERT BO 


INSERT A1 


INSERT A2 



2279412 (1 / 2 ) 

Note: 

2-character keys; maximum is > FFFF; 3 keys per B-tree block 

Figure 2-16. B-Tree Example (Sheet 1 of 2) 
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INSERT A3 
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Figure 2-1 6. B-T ree Example (Sheet 2 of 2) 
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Data Blocks. A data block is a physical record of the file and contains a few words of overhead 
and several logical records as shown in Figure 2-17. The word following the iast logical record has 
a zero value. 


Dec 

Hex 


0-3 

0-3 

Block Number 

4-5 

4-5 

Log Number 

6-7 

6-7 

Space Remaining 

8-1 1 

8-B 

Free Chain Pointer 

12-13 

C-D 

Highest Logical Record ID Used 

14-15 

E-F 

Record Size 

16-17 

10-11 

Logical Record ID 

18- 

1 2- 



Record 


First 

Record 



Last 

Record 


2279413 


Figure 2-17. Data Block Format 
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The fields of a data block are as follows: 


Byte Description 

0-3 Physical record number of the block. 

4-5 Log number that file management assigns when this block is logged. 

6-7 The number of bytes remaining in the block. 

8-11 Free chain pointer. The block is placed in the free chain when a logical 
record is deleted from the block. The block may or may not include 
active logical records. 

12-13 Highest ID assigned to any logical record within the data block. 

14-15 Size (in bytes) of the first logical record inclusive. 

16- 17 The ID assigned to the first logical record. 

18 - First logical record. 


Additional records (if any) follow the first record. For each record, the size and ID precede the 
record. A word of zeros (the record size of the next record) follows the last logical record. 

2.3.4.5 Description of Logical Record. A logical record in a KIF is a blank-suppressed record 
(described in paragraph 2.3.2). The first word of a blank-suppressed record contains the number of 
words of blanks removed and the number of words of data that follow. Following the specified 
words of data is another word with similar counts related to the next portion of the record. This 
pattern continues through the entire record, as shown in the following example: 


1 

1 0 

2 1 

31 

41 

47 

48 52 

222222222 

PUBLIC 

JOHN 

CUE 

333333 

M 

44444 


22794t 4 
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The record is written to the file as follows: 


RECORD SIZE 

-LOGICAL RECORD ID 

NUMBER OF WORDS OF BLANKS 
■NUMBER OF DATA WORDS FOLLOWING 


LOGICAL 


0030 000'3 0008 3232 3232 3232 3232 3250 5542 

4320 0202 4A4F 484E 0302 4355 4520 0306 3333 

3333 4034 3434 3434 \ ' — number of data words following 

NUMBER OF WORDS OF BLANKS 


4C49 

3333 


2279415 


The records of a KIF that has only a primary key are a special case. The characters of the key are 
replaced by blanks in each record and are suppressed. The following example shows the record 
given in the preceding example with a primary key consisting of the entire name, columns 10 
through 40: 


SINGLE KEY ID = 3 KEY = ENTIRE NAME 


001E 

0003 

0005 

3232 

THE 

3232 

KEY FIELD 

3232 

CONTAINS 

3232 

BLANKS 

3220 

OF 06 

3333 

3333 

3333 

4034 

3434 

3434 





2279416 


The record contains 30 bytes instead of 48. The first word following the record number shows 5 
words of data instead of 8. The word that precedes the last block of data replaces a field of 30 
blanks. 

2.3.4.6 KIF Disk Usage. This paragraph explains how to calculate the size of a KIF. The accu- 
racy of the estimate depends on the accuracy of the parameters used in the calculation. These 
parameters are as follows: 

• Physical record size 

• Average blank-suppressed logical record size 

• Sizes of all the keys 

• Size of an ADU on the disk on which the file is created 

• Maxirhum number of logical records 

• Whether the input is sorted 
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The most difficult parameter to estimate is the average blank-suppressed logical record size. This 
is the average size of a logical record if all blanks are removed from all the records. You can easily 
determine the maximum number of logical records if the records are already in a sequential file. 
Otherwise, you must estimate this value. The other values are well defined and should require no 
estimations. 

The disk allocation of a KIF consists of three specific areas: 

• Prelogging area 

• B-tree nodes 

• Data records 

The prelogging area is the only area of the three that has an absolute value. The following formula 
calculates the number of physical records of disk space required for this area: 

NPRprelog = (18* K) -i- 3 

where: 

K is the number of keys. 


NOTE 

In the following formulas, [RD] means to round the number down to 
the nearest integer, and [RU] means to round the number up to the 
nearest integer. 


The B-tree nodes are the records that contain the structures that make KIFs function differently 
from other file types. Only leaf nodes are included in this calculation so that the file estimate can 
be low by a few records. The following formulas estimate the number of physical records required 
for these structures: 


X = PRS - 20 [RD1 
KS -I- 6 

Y = #LR [RUI 
X 

NPR B-tree = Y + (SPLIT * Y) [RU] 
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where: 

PRS is the physical record size. 

KS is the size of the key. 

#LR is the maximum number of logical records. 

SPLIT is 0.1 if the input is already sorted with respect to the key; otherwise, it equals 0.25. 

You must determine a B-tree value for each key in the file. 

The last area includes the data records. The following formulas estimate the number of physical 
records required for this area: 

X = PRS - 16 [RD] 

LRS + 6 

NPRdata = #LR[RU] 

X 

where: 

PRS is the physical record size. 

LRS is the average blank-suppressed logical record size. (If the file has only one key, this 
value should not include the length of the key; that is, assume that the key consists of all 
blanks.) 

#LR is the maximum number of logical records. 

.'he 16 bytes subtracted from the PRS are the overhead of the physical data block. The 6 bytes 
■laded to the LRS are the overhead of each logical record. 

The following formula calculates the total number of physical records required: 

K 

TPR = NPRprelog + NPRdata + Z N PR B-tree i 

i = 1 

where: 

K is the number of keys. 
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Finally, the following formula calculates the total number of ADUs required: 
If PRS> = ADU 


then number of ADUs required = PRS 

ADU 

else number of ADUs required = 

ADU 

PRS 


[RU] * 
1 

[RD] 


NPR total 

*NPR total 


where: 

PRS is the physical record size. 

ADU is the ADU size. 

The following are examples of these calculations. 


EXAMPLE 1 


PRS =864 
ADU = 864 

LRS = 60 (Average blank-compressed key size) 
KS = 20 
K = 1 
#LR =800 

Sorted input (SPLIT =.1) 


A) NPRprelog = (18 * 1) -i- 3 = 21 

B) 864 - 20 _ 32 

20 - 1-6 

^[RU] -I- (.1 *^[RU])[RU] = 25 H- 3 
32 32 

NPR B-tree = 28 

C) 864 - 16 [RD] = 12 
60-1-6 

NPRdata = 800[RU] = 67 
2 
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NPRtotal = NPRprelog + NPR B-tree + NPRdata 
= 21+28 + 67 
= 116 

ADUs = ^[RU] * 116 = 116 
864 

EXAMPLE 2 


PRS =864 
ADU = 864 
LRS =60 
KS1 =20 
KS2 =20 
KS3 =20 
K =3 
#LR =2600 

Random input (SPLIT = .25) 

A) NPRprelog = (18 * 3) + 3 = 57 

B) 864 - 20 [RD] = 32 
20 + 6 


2600 [RU1 + (.25*26^[RU])[RU] = 82 + 21 
32 32 

NPR B-tree(l) = 103 key 1 
NPR B-tree(2) = 103 key 2 
NPR B-tree(3) = 103 key 3 

C) 864 - 16 [Rpj _ -|2 


NPRdata = 2600 rpyi — 217 
12 

NPRtotal = NPRprelog + NPRB-tree(l) + NPRB-tree(2) + NPRB-tree(3) + NPRdata 
= 57 + 103 + 103 + 103 + 217 
= 583 

ADUs = 864 jRU] * 583 = 583 
864 
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3.1 SCI OVERVIEW 

The System Command Interpreter (SCI) is the principal interface between the operating system 
and the user. SCI operates In a job and executes commands In both the Interactive and batch 
modes. Thus, SCI can execute in an interactive job at a terminal or from a batch stream without an 
associated terminal. Except for the way in which it accesses commands and their parameters, SCI 
executes in the same manner for the interactive mode as for the batch mode. 

In the interactive mode, SCI displays prompts that request the values of command parameters. 
SCI can have one associated foreground task and one background task in the interactive mode. 

In the batch mode, you specify parameters by field prompt assignments in the command stream. 
The batch stream executes in background. A background task or an SCI batch job receives a copy 
of the synonyms and logical names when execution begins. Changes in the background or the 
batch mode synonyms and logical names do not affect the foreground values. 

You can initiate an independent SCI batch job by using the Execute Batch Job (XBJ) command. 
Since batch jobs do not require associated terminals to execute, you can start any number of 
them from a terminal. Figure 3-1 illustrates the concept of SCI interactive and batch modes. 

The name manager task maintains synonyms and logical names for jobs running under DNOS. 
Synonyms are local to a job; however, logical names are either job-local or global In scope. You 
can access synonyms and logical names for the job from SCI utilities or user tasks by issuing 
supervisor calls (SVCs) to the name manager. The name manager retrieves synonym and logical 
name definitions. However, you should call the appropriate SCI interface S$ routines to access 
synonyms rather than issuing the SVC. This allows you to conform to any change in SCI imple- 
mentation by linking the updated version of the S$ routines. 

A synonym is a variable in the SCI language and represents either a string of characters or a null 
value. It functions as an alternative for another string. It Is usually shorter than the text it replaces 
and more convenient to use. 

A logical name is a user-specified character string used to name a resource within the scope of a 
job. A resource can be referenced by the logical name instead of a pathname or a device name. 
Consequently, a logical name resolves to a pathname or device name. A logical name can also 
appear as the first component of a pathname. Unlike synonyms, logical names can have asso- 
ciated parameters. This provides a general method of passing user-defined parameters to a task. 
Parameters are used to provide execution time values for SVC control blocks. Figure 3-2 shows 
the flow for accessing synonym and logical name tables from an SCI utility. 
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The synonym table and logical name table are copied from a disk file when a user logs on. The file 
is usually identified with the user ID in the .S$USER directory. However, it is also possible to use 
the Modify Terminal Status (MTS) command to have the user specify the file during logon. The 
name manager accesses memory copies of synonyms and logical names. The synonym and logi- 
cal name table in memory are written back to the disk file when the interactive SCI terminates. 

When several users are logged on with the same user ID and job name, they can share an environ- 
ment of synonyms and logical names by responding YES to the RECONNECT prompt at log-on. 
Each user starts the session with the same set of synonyms and logical names. Each has his own 
environment as he makes changes. The environment of the last person to sign off from this job is 
saved on the disk. 

In the interactive mode, SCI also uses the terminal local file (TLF). It provides a buffer on disk for 
lines to be displayed to the user. The lines are buffered so that the interactive SCI user can scroll 
through them. The name of the file is determined from the SCI mode and the terminal number, as 
follows: 

• Foreground: .SSFTLFxx (xx = terminal number) 

• Background: .S$BTLFxx (xx = terminal number) 

• Batch SCI Job: .S$JLxxxx (xxxx = job ID) 


3.2 USER-DEFINED SCI COMMAND PROCEDURES 

You can extend SCI by defining SCI command procedures for specific applications or by redefin- 
ing or modifying the command procedures supplied with the system. 

The next paragraphs give a brief overview of the following topics: 

• SCI primitives 

• Command procedures 

• Command processors 

After the overview, these topics are covered in detail as the rest of the section explains how to 
create your own SCI command procedures and command processors. 
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3.2.1 SCI Primitive 

A primitive is the basic building block of the SCI language. Primitives allow you to create com- 
mand procedures, which enable you to create additional commands that meet your application 
needs. 

3.2.2 Command Procedure 

A command procedure Is a sequence of SCI statements (commands, primitives, or menu displays) 
that SCI executes. A command and its associated field prompts are defined in the command 
procedure. 

You can use any existing SCI commands and any of the SCI primitives in a command procedure. 

SCI command procedures are stored in a directory called a procedure library. Use separate 
libraries for the SCI commands provided with DNOS and for those you create. This precaution 
enables you to modify the libraries separately, since new releases can effect the SCI command 
library that comes with DNOS. 

3.2.3 Command Processor 

A command processor is a task that an SCI procedure executes to perform a specified action. The 
processor can be written In either a high-level language or assembly language. The processor can 
access synonyms and logical names to communicate with SCI. For many applications, the proce- 
dure calls the processor without passing any data to the processor. In more complicated cases, 
the procedure passes parameters to the processor via the FARMS parameter of .BID, .DBID, 
or .QBID. 

The instructions or statements of the source code for the command processor vary with the lan- 
guage used and the action to be performed. The command processor can contain any number of 
instructions and can use the services of SCI. 


3.3 SCI LANGUAGE SYNTAX 

The SCI language consists of a set of commands (primitives), special characters, and variables. 
Command procedures use several SCI characters specifically defined for use in these procedures. 
Table 3-1 defines these special characters and the SCI language syntax, and subsequent para- 
graphs discuss primitives and variables. 
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Table 3-1. Special SCI Characters 


Character 

Meaning 

! 

Indicates the end of a record. Comments may occur after the ! but cannot 
span lines. 

* 

If it is in column 1, it indicates a comment statement; if it precedes a valid 
field prompt type (Table 4-4), it indicates that the field prompt is optional. 

@ 

Indicates that SCI should treat the character string following the @ sign 
(and preceding the next nonalphanumeric character) as a synonym. If the 
synonym was previously defined, the value of the synonym replaces the @ 
sign and character string; otherwise, the value of the synonym is defined as 
the character string itself. 

& 

Indicates that the character string following the ampersand is a field 
prompt. The value replaces the ampersand and the character string; if no 
value is specified, a null string is indicated. 

— 

If it precedes a valid field type, the initial value and the user response are 
not echoed at the terminal. In a batch stream, the response is replaced by 
four dashes. 

A 

Delimits synonyms when concatenating them with other values or 
synonyms. 

— 

If it is in column 1, it causes the line in a batch stream to be executed but 
not written to the listing file. 


In the following examples, lowercase characters Indicate values supplied by the user; Items 
enclosed by [ ] are optional. 

The basic syntax of a command in the SCI language is: 

command[field prompt(s)] 
where: 

command is the SCI command and field prompt(s) is a list of field prompt assignments. 

At least one blank space must separate the command from the field prompt(s); blank spaces can 
also be entered before the command. Commas separate field prompts which can continue on 
successive lines. 
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The basic syntax of a primitive in the SCI language Is: 

primitive [keyword list] 
where: 

primitive is the SCI primitive and keyword list is a list of keywords associated with the 
primitive. 

At least one blank space must separate the primitive from the keyword list; blank spaces can also 
be entered before the primitive. The keywords are separated with commas and can continue on 
successive lines. 

Any SCI language line (except a comment line) whose last nonblank character is an equals sign 
( = ) or a comma (,) is continued on the following line. 

The following example is processed as a single SCI command: 

IDT YEAR=1980, M0NTH=4 , DA Y=27 , 

H0UR=18 ,MINUTE=56 

Note that blank spaces can also follow or precede the commas separating field prompts. A 
continued list of field prompts can begin anywhere on subsequent lines. Field prompts on succes- 
sive lines are usually placed directly below the initial line of field prompts for appearance and 
readability only. 


3.4 SCI LANGUAGE VARIABLES 

SCI language uses the following three types of variables: 

• Synonyms 

• Logical names 

• Field prompts 

Synonyms and logical names allow you to reference an I/O resource by an abbreviated name of 
the resource and are applicable to every task in a job. Field prompts are assigned values deter- 
mined by the field prompts within a command. The following paragraphs define these variables 
and discuss their uses. 
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3.4.1 Synonyms 

Synonyms are names that you assign to represent I/O resources using any of the following: 

• .SYN primitive 

• Assign Synonym (AS) command 

• S$SETS used in an application program 

• Name Manager SVC (> 43) execution 

The first three are user interfaces to the Name Manager SVC. This section discusses the .SYN 
primitive, S$SETS, and the AS command. The DNOS System Command Interpreter (SCI) Manual 
explains the AS command and the DNOS SVC Reference Manual explains the Name Manager SVC 
execution. 

The following example shows how the .SYN primitive defines a synonym equivalent to the direc- 
tory component of a pathname: 

.SYN MY=DS02 .MKC . SOURCE 

The preceding example assigns the synonym MY to represent the directory DS02.MKC.SCURCE. 
As a result, a file in this directory can be referenced as follows: 

[] SF 

PATHNAME: MY. DATA 

When using synonyms, there are three ways to determine a synonym value, as follows: 

• In the context of an SCI command procedure, precede the synonym name with an at 
sign(@). 

• Use S$MAPS/S$SNCT in an application program. 

• Execute the Name Manager SVC (> 43). 

The first two are user interfaces to the Name Manager SVC. S$MAPS and S$SNCT are discussed 
later in this section. 

When the @ sign precedes the synonym name in a string or expression, the synonym value 
replaces the synonym. For example. If the string DEVICE is previously defined as a synonym with 
the value LP01: 

"LISTING DEVICE IS SDEVICE" 

is evaluated by SCI as: 

"LISTING DEVICE IS LP01" 
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If a synonym does not have a previously assigned value, SCI uses the synonym name as the value. 
For instance, if the synonym MY has not been defined, then the following is true: 

.SYN X=aMY . MKC . DATA 

is equivalent to 

.SYN X=MY .MKC . DATA 

SCI reads the synonym string characters from right to left, identifying the string following the @ 
sign as a synonym name. If there is more than one @ sign within a string of characters and the @ 
signs are not preceded by a special character (that is, the character is not a dollar sign, bracket, 
back slash, or alphanumeric), the string following the first @ sign encountered is evaluated and 
the synonym name is replaced by the value. 

For example, if the following synonym is defined as: 

.SYN GHI=123 

and is used in the following synonym definition: 

.SYN ABC=aDEFaGHI 

SCI evaluates the string GHI, reading from right to left, and replaces the synonym with its defined 
value as follows: 

.SYN ABC=aDEFl23 

SCI begins reading from right to left again, finds the @ sign and evaluates the entire string 
@ DEF123 (not @ DEF). Since DEF123 has not previously been defined, the .SYN primitive assigns 
the character string DEF123 as the value for the synonym ABC. 

Assuming the GHI synonym is still defined as 123 and the synonym DEF is assigned the following 
value: 


.SYN DEF=SRC 
the following synonym definition: 

.SYN ABC=aDEF .aGHI 
would be evaluated as follows: 
.SYN ABC=SRC.123 


3-8 


2270510-9701 



Extending SCI 


In situations where there is no special character in the string, use the caret to separate two 
synonyms or enclose a synonym. The caret allows proper synonym evaluation by SCI, demon- 
strated in the following example. 

The synonyms OBJ and PGM are defined and used in the following .SYN primitive; 

.SYN 0BJ=MY 
.SYN PGM=PR0GA 

.SYN RESULT = aOBJ'^aPGM 

SCI evaluates the synonyms OBJ and PGM separately when the caret is inserted and defines the 
synonym RESULT as: 

.SYN RESULT=MYPROGA 

This process of reading and evaluating synonyms applies to all commands and is not unique to 
the .SYN primitive; the .SYN primitive is used only as an example for simplicity. When a line is read 
by SCI, textual substitution is performed immediately from right to left, without regard to the 
command being processed. After the synonym is evaluated, the command line is processed 
accordingly. 

Because of the textual substitution on a line-by-line basis, a primitive split over several lines can 
have different results from a primitive written on one line. Consider the following example: 

.SYN X=ABC 

.SYN D=1 

.SYN D=ax, E=aD 

These lines generate the value ABC for D and the string 1 for E. Now, consider a second example; 

.SYN X=ABC 
.SYN D=1 
.SYN D=ax, 

E = aD 

These lines generate the value ABC for both D and E because the textual substitution in the last 
line occurs after the .SYN D = @X line is processed. 

A synonym can be used without any problems to represent an entire pathname or only the first 
component of a pathname. However, because of the significance of special characters in the eval- 
uation of synonyms, the use of synonyms to represent secondary components of a pathname can 
cause problems. For example, if S is a synonym defining SOURCE and is used in 
@VOL1.MYDISK.S, the synonym is not properly evaluated with the @ sign preceding the path- 
name. Synonyms can be used as secondary components if the @ signs are properly placed in the 
string evaluation. The correct synonym representation is VOL1.MYDISK.@S and is evaluated as 
VOL1 .M YDISK.SOURCE. 
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The period acts as a delimiter in concatenation for synonyms. For example, if the synonym ABC 
has a value of XYZ, the concatenation of ABC to the character string .DEF would have the 
following results: 

aABC . DEF=XYZ . DEF 

A character string can be concatenated to a synonym, as shown in the following example (where 
LAST represents the character string): 

LASTaXYZ 

where: 

@XYZ represents the value of a synonym. 

In addition to the synonyms you create, SCI maintains some synonyms which can be accessed by 
command procedures. These synonyms are listed in Table 3-2. 


Table 3-2. SCI Maintained Synonyms 

Synonym Definition 

$$BT Task run ID of last background task. 

$$BC Completion code of last executed background task. 

$$CL List of current command procedure directories 

$$MO Two-digit hexadecimal code for the SCI mode; 

00 = Batch mode 

01 = TTY mode 
OF = VDT mode 

$$SI Eight-character site name for this system. 

$$ST Two digit decimal station number (for example, 09). When executing in a 

batch job, $$ST is assigned a value of 00. 

$$UI User ID of one to eight characters (for exampie, SYSTEM). 

ME Four-character station name (for example, ST09). When executing in a 

batch job, ME is not assigned a value. 


Table 3-3 lists the synonyms which are generated by command processors and SCI when using 
the error handling facility. 
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Table 3-3. Message Processing Synonyms 

: 9 

Synonym Definition 

$$CC Hexadecimal completion code that can be returned by a command proces- 

sor via the S$TERM or S$STOP routine 

$$ES Error source indicator for the last status or error message 

$$FN File name within directory .S$MSG from which the last message was 

generated 

$$MN Internal message number of the last error or status message declared by 

either SCI or a command processor 

$$VT Text string containing information about the last error or status message 


3.4.2 Logical Names 

Logical names appear functionally equivalent to synonyms, but they are significantly different. 
Like synonyms, logical names are sets of names and values; however, logical name values can 
include a set of parameters in addition to the resource name. 

The logical name value is always assumed to be an I/O resource. Values associated with the logi- 
cal names are descriptions of I/O resources, such as logically concatenated files or spooler 
devices. Logical names can have pathnames and descriptive parameters (for example, job- 
temporary or ANSI format) and can be job-local or global in scope. The resolution automatically 
occurs within DNOS each time the logical name is used in a context as an I/O resource. Treat the 
logical name as an I/O resource once it is defined. 

There are two ways that you can define a logical name: 

• Execute the Assign Logical Name (ALN) command. 

• Execute the Name Manager SVC (> 43). 

The ALN command is a user interface to the Name Manager SVC and is described in the DNOS 
System Com mad Interpreter (SCI) Reference Manual. Refer to the DNOS SVC Reference Manual 
for an explanation of the Name Manager SVC. 

3.4.3 Environment and Scope of Name Definitions 

Within a single job, each task has access to the set of synonyms and logical names that other 
tasks of the job have assigned. The effects that these name definitions have on an executing task 
can be thought of as the task’s environment. 

When a background task is started via a .QBID primitive, a new snapshot of the SCI environment is 
made and the new task executes in that environment. None of the synonym and logical name defi- 
nitions changed by either task (subsequent to the bid) affect the environment of the other. 
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3.4.4 Field Prompts 

A field prompt is the character string which req jests a valid response to execute an SCI com- 
mand. This character string contains a maximum of 28 characters, including embedded blanks. 

Reference to the field prompt value can be made t>y preceding the field prompt with an ampersand 
(&). The following example refers to the value of the specified field prompt: 

&INPUT PATHNAME OR LUNO 

Field prompt values can include an assigned synonym. To reference a field prompt which con- 
tains a synonym as its value, the at sign (@) precedes the ampersand. The following example indi- 
cates that the synonym resolution is to be performed on the field prompt value: 

a&INPUT FILE PATHNAME OR LUNO 


Use the ampersand also when concatenating character strings, strings, and variables. For 
instance, the character string ABC is concatenated to the value of the field prompt FILE in the 
following example: 

ABC&FILE 

A field prompt can specify an appropriate response type for the acceptable values. When defining 
response types for field prompts, enclose the response type in parentheses to indicate that a list 
can be accepted as the value. 

Table 3-4 lists the types of valid field prompts. The brackets [] indicate optional items and the 
parentheses ( ) indicate an initial value for the prompt. 


Table 3-4. Valid Field Prompt Types 
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The following features are common among field prompts: 

• An asterisk (*) preceding the field prompt type indicates a response is optional and 
need not be supplied. 

• if an initiai vaiue begins with a doliar sign ($), then a nuli string is used as the initial 
value. 

• The value of a field prompt can be a single value or a value list; however, DEFAULT can 
only be a single value. When defining a field prompt type in a command procedure, 
enclose the type in parentheses to allow a value list. Code a value list as a sequence of 
single Items separated by commas when defining the response to a field prompt inter- 
actively. However, if a value list is entered in a batch stream, enclose the list in 
parentheses. If a list contains only one item, parentheses are not required. 

For example, in a command procedure, FILE = ACNM declares the field prompt 
FILE and requires a value of the type ACNM. INPUT = (ACNM) indicates that 
INPUT can be a single value or a list of values which are of the ACNM type. When 
defining responses to these prompts interactively, FILE = DS04. LIST and 
INPUT= MY.MKC.PROGA,MY.MKC.PROGB are valid value assignments for FILE and 
INPUT, respectively. 

• Each field prompt type can have a specified initial value. Enclose initial values which 
are lists in quotation marks (“”). The DEFAULT type requires that an initial value be 
specified. Represent the null value for a field prompt, referred to as a null string, by a 
pair of quotation marks 

• A field prompt can be specified as having more than one possible field prompt type. For 
example, a response to a prompt can be a pathname or LUNO as used in this Execute 
Task (XT) command prompt: 

PROGRAM FILE OR LUN0= A C NM / R AN G E ( 0 , 0 F F ) 

The preceding example is known as an alternate prompt type. Separate each field prompt 

type by a slash (/). The DEFAULT type cannot be specified as an alternate type. 

The following paragraphs discuss each field prompt type and its format. The prompts used in the 
format examples are used for simplicity and may not be in their complete forms. 

3.4.4.1 ACNM Field Prompt Type. The ACNM field prompt type allows a response that is a file 
name, channel name, or device name. The following is an example of the ACNM field prompt type: 

FILE PATHNAME = *ACNM('*a$SF$P") 
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In the previous example: 

• The asterisk indicates that the response is optional. 

• The response must be a single value. 

• The at sign (@) preceding the set of characters, $SF$P, indicates the string represents a 
synonym. 

• The parentheses around the set of characters, “@$SF$P”, indicate that SCI will use the 
value of the synonym as the initial value for the field prompt. 

• The quotation marks around @$SF$P cause the entire value of the synonym to be 
shown. Without the quotation marks, invalid parameter messages can occur. 

3.4.4.2 DEFAULT Field Prompt Type. The DEFAULT field prompt type assigns a default value to 
a field prompt. The DEFAULT type has the following three characteristics; 

• Syntax is not checked. 

• Field prompts of the DEFAULT type are not displayed in interactive mode but they can 
be explicitly assigned a value in batch mode or expert mode. 

• The field prompt is assigned a default value only when the previous value was not 
assigned to the field prompt in batch mode or expert mode. 

The following example illustrates the DEFAULT field prompt type: 

DISPLAY=DEFAULT(Y) 

The Y is a response previously assigned to the field prompt. It is only necessary to enter a 
response when you do not want the default. 

3.4.4.3 ELEMENT Field Prompt Type. The ELEMENT field prompt type allows a list of accept- 
able responses to a field prompt to be specified. Using the near-equality algorithm discussed in 
the System Command Interpreter (SCI) Reference Manual, SCI attempts to match the response 
entered with each element in the list. If the response fails to match any item or matches more than 
one item, the type verification fails. Each item in the list can have a replacement value. Whenever a 
specific item in the list is matched, the value assigned to the field prompt is the replacement value 
and not your response. If the terminal is in default VDT mode (see the Modify Terminal Status 
(MTS) command in the System Command Interpreter (SCI) Reference Manual), the replacement 
value is echoed to the screen and replaces your response. 

The following example illustrates the ELEMENT field prompt type: 

ARE YOU SURE=ELEMENT(Y=YES,N) 

In this example, the response must begin with aY or N character. It is recommended that replace- 
ment values match the response in accordance with the near-equality algorithm. 

If you respond with YOU BETCHA, the value of ARE YOU SURE is YES. However, if the response 
was NO WAY, the value of ARE YOU SURE is NO WAY. 
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3.4.4.4 INT Field Prompt Type. The INT field prompt type allows a response to be a 32-blt 
hexadecimal or decimal integer expression In the range of >80000000 through >7FFFFFFF 
(-2147483648 through 2147483647). The following example illustrates the INT field prompt type 
with the initial value enclosed in parentheses: 

PARM1= INT(O) 

In this example, the parentheses around the value zero indicate the initial value. 

3.4.4.5 NAME Field Prompt Type. The NAME field prompt type allows a response to be a char- 
acter string beginning with a dollar ($) sign or a letter (A - Z). The remaining characters of the 
string can contain letters, numbers, $, [, ], or \. The following example illustrates the NAME field 
prompt type: 

TASK NAME=*NAME 

In this example, an asterisk preceding the field prompt type indicates that the response is 
optional. 

3.4.4.6 RANGE Field Prompt Type. The RANGE field prompt type has the same function as the 
INT type; however, in addition, you can specify numeric upper and lower bounds. The following 
example Illustrates the RANGE field prompt type: 

LUNO=*RANGE(0,255) 

In this example: 

• The asterisk preceding the field prompt type *RANGE(0,255) indicates that the response 
is optional. 

• The response must be in the range of 0 through 255. 

3.4.4.7 STRING Field Prompt Type. A STRING field prompt type allows a response that is a 
string which does not contain quotation marks, exclamation marks, equals signs, parentheses, or 
commas. 

The initial value specified for a STRING type can be enclosed by quotation marks, denoting it as a 
quoted string. A quoted string can contain quotation marks, exclamation marks, equals signs, 
parentheses, or commas within the enclosed string. However, you must be cautious when you use 
a string containing quotation marks, as they must always be used in pairs. 

An error occurs if an unpaired quotation mark is used within the string, as in the next example: 

"ENTER TO "RESUME OPERATION" 
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There should always be an even number of quotation marks in a quoted string, as in the next 
example: 

"ENTER TO "RESUME OPERATION"" 

A pair of double quotation marks can also be used to represent a null string 

The following example illustrates the STRING field prompt type: 

I NPUT=* (STRING) ("a$XE$S") 

The following statements are true: 

• The parentheses around the field prompt type STRING indicate that the response can 
be a single value or a value list. 

• The asterisk preceding the field prompt type (STRING) indicates that the response is 
optional. 

• The at sign (@) preceding the characters $XE$S indicates that the value of the synonym 
is to be substituted for the string $XE$S. 

• The parentheses around the set of characters “@$XE$S” indicate that the value of the 
synonym $XE$S is used as the initial value for the field prompt. 

• The quotation marks enclosing the set of characters @$XE$S allow the value of the 
synonym $XE$S to be a list of values. 

3.4.4.8 YESNO Field Prompt Type. The YESNO field prompt type allows a response that is an 
alphabetic character string beginning with a Y or an N character. The following example illus- 
trates the YESNO field prompt type: 

ARE YOU SURE?=YESNO 

In this example, the response must begin with a Y or an N. 


3.5 SCI PRIMITIVES 

SCI primitives are the lowest-level members of the SCI language and are used to create command 
procedures and command processors. When applicable, primitives follow the guidelines dis- 
cussed in the preceding paragraphs. Table 3-5 lists the SCI primitive notations and Table 3-6 lists 
the available primitives and their associated parameters. Subsequent paragraphs discuss each 
SCI primitive. 
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Table 3-5. SCI Primitive Notation 


Notation 

Meaning 

Uppercase 

Enter the item as shown. 

Lowercase 

Enter an item of this type. 

No marks 

The item is required. 

[ ] 

The item is optional. 

Item. ..item 

More than one. item of this type can be used. 

Items are separated by commas. 

Italics 

Indicates the type of item required. 

/ 

Indicates alternate items. 

Table 3-6. SCI Primitives 

Primitive 

Command 

Parameters 


.PROC name[{fuU name)][ = int][, field prompt list] 

.EOP 

.PROMPT [{full name)][ = int][, field prompt list] 

.SYN name = “value”. ..name = “value” 

.EVAL [mode][ = YES/NO, Jname = value 

.SPLIT LIST = (list)[, FIRST = name][, REST = name] or 

LIST = “strlng”[,F\RST = name][, REST = name] 

[.CHARACTER = “sfr/ngf’!, POSITION = /77f][, STATUS = name] 

.SVC [$name ]DATAIBYTEITEXT = value(s)... 

[$name ]DATA/BYTE/TEXT = va/ue^sj 

.IF op1, relation, op2 

.ELSE 

ENDIF 

.LOOP 

.WHILE op1, relation, op2 
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Table 3-6. SCI Primitives (Continued) 


Primitive 

Command 

Parameters 

.REPEAT 


.UNTIL 

opt, relation, op2 

.EXIT 


.BID 

TASK = namelint[,LUHO = /A?f][,CODE = int] 

[.PROGRAM FILE = acnm][,PARMS = (string. ..string)] 

[.UTILITY] 

.DBID 

TASK = namelintlLUNO = int][,CODE = int] 

[.PROGRAM FILE = ac/?m][.PARMS = (string. ..string)] 

[.UTILITY] 

.QBID 

TASK = namel lnt[, LUNO = /77f][.CODE = int] 

[.PROGRAM FILE = ac/7/77][.PARMS = (string...string)] 

[.UTILITY] 

.DATA 

[acnm][.EXTEND[ = YES/NO]][.SUBSTITUTION[ = YES/NO]] 

[.REPLACE[ = YES/NO]] 

.EOD 


.STOP 

[TEXT = sfr/'ng][.CODE = int] 

.USE 

{pathname...pathname] 

.OPTION 

[PROMPT[ = sfr/V7g]][.MENU[ = name]] 

[.PRIMITIVES[ = YES/NO]][.LOWERCASE[ = YES/NO]] 

.MENU 

[menu name] 

.SHOW 

filename...fiiename 


3.5.1 .PROC and .EOP Primitives 

you can use the .PROC primitive to begin an SCI procedure definition which must end with the 
,EOP primitive. Use the .PROC primitive to install the command procedure into a command proce- 
dure library. The following represents the .PROC format: 

.PROC name[{full name)][ = int][, field prompt list] 

The name parameter, which must be the first parameter, defines the name of the procedure. You 
san give an optional full name, enclosed in parentheses, immediately following the name. The full 
name is displayed on the terminal when the procedure is executed. 
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The Int field is optional and determines the privilege level used for the procedure being defined. 
This field must follow the full name if you specified a full name. Table 3-7 shows the different priv- 
ileges which can be specified. 

Command privilege levels are assigned according to your system knowledge and job require- 
ments. If a user ID privilege level is numerically lower than the privilege level assigned to a particu- 
lar command, you cannot issue that command. The system manager uses the Assign User ID (AUl) 
or the Modify User ID (MUI) command to establish privilege levels. Privilege levels can be assigned 
with respect to the power of the command and the knowledge and trustworthiness of the user. The 
default value for the privilege level is 0. 


Table 3-7. Command Privilege Levels 
Level Meaning 

0 Lowest level of access privilege; for example, Create File (CF) 

1 Defined by the System Manager 

2 System access level; for example, Kill Task (KT) 

3 Defined by the System Manager 

4 Management access level; for example. Assign User ID (AUl) 

5 Defined by the System Manager 

6 Combination of System and Management; for example. Execute System Generation 
Utility (XSGU) 

7 Defined by the System Manager 


The field prompt list is a character string following the optional privilege level. A field prompt list 
is formatted as: 

field prompt = field prompt type 
where: 

the field prompt type is one of those listed in Table 3-4 and follows the rules defined for it. 

A maximum of 22 field prompts can be defined for a command. 
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The following example illustrates the .PROC and ,EOP primitives used in a command procedure: 

.PROC EX (EXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM 
SF FILE="&INPUT PATHNAME" 

. EOP 

in this example, the full name of the command procedure Is EXAMPLE PROC and the SCI com- 
mand is EX. The specified privilege level is zero, therefore, the command is available to any user. 
INPUT PATHNAME is a field prompt. INPUT PATHNAME requires an ACNM field prompt type for 
its response. The SF command uses the response to INPUT PATHNAME as an initial value. This 
command procedure could be used to install the EX command on the system. 

When you issue the EX command, EXAMPLE PROC is displayed along with the iNPUT 
PATHNAME prompt. The cursor is positioned in the response fieid and is ready for your entry. 
Press the RETURN key after you enter a response. The SF command is bid by the EX command 
procedure and the file identified for the INPUT PATHNAME response is dispiayed. (It is not neces- 
sary to completeiy understand the command procedure at this point. Detaiis of command proce- 
dures are explained iater in this section.) 

It is good programming practice to indent the command procedure to show the control structures 
in it. The .PRCC processor preserves such indentation when it creates the output fiie. 

3.5.2 .IF, .ELSE, .ENDIF Primitives 

The SCI language uses the constructions IF-THEN and IF-THEN-ELSE to create a conditional 
primitive. The .IF primitive must be used In conjunction with the .ENDIF primitive. The .ELSE primi- 
tive is an optional primitive used with the .IF and .ENDIF primitives. The .ENDIF primitive termi- 
nates the .IF primitive. 

.IF op 7 , rela tion, op2 


.ELSE 


.ENDIF 

If the .IF condition is true, then statements immediately following the .IF primitive are executed. If 
the condition is false, any statements following the .ELSE primitive (if present) are executed. Exe- 
cution then continues with statements following the .ENDIF primitive. 
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The .IF primitive must contain a condition using a reiation defined in the foilowing iist: 

Relation Meaning 


op1 ,EQ,op2 
op1,NE,op2 
op1,GT,op2 

op /,LT, op2 

op7,GE,op2 

opl,LE,op2 

op7,IS,op2 

op7,ISNOT,op2 


op1 is equal to op2 
op1 is not equal to op2 

op1 is greater than (foliows) op2 in the ASCIi coiiating 
sequence 

op1 is less than (precedes) op2 in the ASCIi coiiating sequence 

either GT or EQ is true for op1 and op2 

either LT or EQ is true for op1 and op2 

op1 is of type op2 

op 7 is not of type op2 


The EQ, NE, GT, LT, GE, and LE reiations allow op7 and op2 to be strings, variabies, or concaten- 
ated strings. The relation parameter designates the type of comparison which is performed on the 
operands, if both op1 and op2 are numeric, a numeric comparison is made; otherwise, a string 
comparision is performed. 


The IS and ISNOT relations require op2 to be a fieid prompt type; aiternate types cannot be speci- 
fied. A check is made to verify that op7 satisfies the type specified by op2. The foliowing exampie 
illustrates the IS relation: 


S 


TATION ID = RANGE (0, OFF) /ELEMENT(ME) ("a$$ST") 


IF "&STATI0N ID”, IS, RANGE(0,0FF) 
SYN $XT$SID=”&STATION ID” 

ELSE 

SYN $XT$SID=”a$$ST” 

ENDI F 


Note that the fieid prompt defines aiternate types of responses, RANGE and ELEMENT. The .IF 
statement verifies that the vaiue specified was of the RANGE type. 
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You can use any SCI primitives (excluding .PROC and ,EOP primitives) between the .IF and .ENDIF 
primitives. You can use the .IF primitive within other .IF primitives with a maximum of 32 levels of 
nested conditionals. The following example uses the .IF, .ELSE, and .ENDIF primitives; IAN and 
CAN of the CC (Copy Concatenate) command represent the input and output pathnames, 
respectively. 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM, 

OUTPUT PATHNAME=ACNM, 

DISPLAY OR COPY?=ELEMENT(D=D, C=C) (DISPLAY) 

.IF &DISPLAY, EQ, D 

SF FILE="&INPUT PATHNAME" 

.ELSE 

CC IAN="&INPUT PATHNAME", 

0AN="&0UTPUT PATHNAME" 

. ENDIF 
. EOP 

The .IF primitive compares the &DISPLAY to the character D. &DISPLAY is the value of the 
response to the DISPLAY OR COPY? prompt; the character D represents a possible value for the 
response. If &DISPLAY and D are equivalent, the SF command procedure is bid and the value rep- 
resented by &INPUT PATHNAME is displayed. If the response to DISPLAY OR COPY? does not 
match D, the .ELSE primitive bids the Copy/Concatenate (CC) command procedure to copy the 
contents of the file specified for INPUT PATHNAME to the file specified for OUTPUT PATHNAME. 
The .ENDIF primitive terminates the .IF comparison and execution continues with the primitives 
or commands following the .ENDIF. 

3.5.3 .PROMPT Primitive 

The .PROMPT primitive reduces the need for secondary command procedures, avoiding large 
command procedure libraries. Additional overhead involved in processing a new command proce- 
dure is also eliminated. The syntax for the .PROMPT primitive is as follows: 

.PROMPT [{full name)][ = lnt][, field prompt list] 

The field prompts defined by .PROMPT are displayed on a different screen from those defined by 
.PROC (that is, the screen is cleared and the new prompts are displayed). 

The full name parameter is optional and specifies a character string to be displayed when the 
primitive is executed in interactive mode. The Int parameter is the lowest privilege level assigned 
to the user ID which permits execution of the procedure. The priviiege levei specified for .PROMPT 
can be higher than the level specified by .PROC; however, it is not recommended. The field prompt 
list parameter is a series of field prompts. 
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The following example illustrates the .PROMPT primitive; 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM, 

OUTPUT PATHNAME=ACNM, 

DISPLAY OR COPY?=ELEMENT(D=D, C=C) (DISPLAY) 

.IF &DISPLAY,EQ,D 

SF FILE="&INPUT PATHNAME" 

.ELSE 

C 

. PROMPT 
. I F 

. ENDI F 
. ENDI F 
. EOP 

The .PROC, .iF, .ELSE, and .ENDiF primitives execute as previously explained. The .PROMPT prim- 
itive displays the DELETE FILE? prompt. The character string SUPPLEMENTARY QUESTION 
defines the optional full name parameter. 

3.5.4 .SYN Primitive 

The .SYN primitive assigns values to synonyms. Synonyms and their values are maintained in the 
synonym table. The .SYN primitive has the following format: 

.SYN name = “value”. ..name = “value” 

The name parameter specifies the synonym name. The value parameter is a string, variable, or 
concatenated expression. Quotation marks enclosing the value are recommended to ensure cor- 
rect interpretation of the value string. 

A string enclosed In quotation marks indicates that the value specified is a list and is to be treated 
as a single item. A value list must be enclosed in quotation marks as shown in the following 
example: 

.SYN A = “1,2,3” Legal 
.SYN A = 1,2,3 Illegal 

Synonyms can be assigned string values containing special characters. To properly handle the 
special character, enclose the string in quotation marks. For instance, as a special character, the 
exclamation mark (!) indicates an end of record. If you use the ! in a character string, enclose the 
string in quotes to include the characters following it. For example; 

.SYN A = “HELLOITHERE” THERE is included in the string. 

.SYN A = HELLOITHERE THERE is not included in the string and is regarded as a 

comment. 


C IAN="&INPUT PATHNAME", 
0AN="&0UTPUT PATHNAME" 
(SUPPLEMENTARY QUESTION), 

DELETE FILE?=ELEMENT(Y=Y,N=N)(NO) 
&DF , EQ , Y 

DF PATHNAME="&INPUT PATHNAME" 
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To avoid synonym table overflow, delete synonyms which are no longer necessary. Assigning a 
null value (“”) to a specified synonym deletes the synonym from the synonym table. 

The following example illustrates the .SYN primitive used in a command procedure: 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM, 

OUTPUT PATHNAME=ACNM, 

DISPLAY OR COPY?=ELEMENT(D=D, C=C) (DISPLAY) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$0P="&0UTPUT PATHNAME" 

.IF &DISPLAY, EQ, D 

SF FILE=a$EX$IP 

.ELSE 

C 

. PROMPT 
. I F 

. ENDI F 
. ENDI F 
. EOP 

This example is similar to the example for the .PROMPT primitive. In addition, this command pro- 
cedure assigns values to the synonyms $EX$IP and $EX$OP which you can access by other com- 
mand procedures. 

3.5.5 .EXIT Primitive 

The .EXIT primitive terminates the execution of the current command procedure. (Use the .EOP to 
terminate the definition of the command procedure.) The .EXIT primitive can be used as often as 
necessary at any point within a command procedure definition. Do not use the .EXIT primitive 
however, within a batch stream. 

The .EXIT primitive does not have any parameters to be defined, and it uses the following format: 

. EXIT 


IAN 

=a$E 

X$IP, 


OAN 

=a$E 

X$0P 


(SUP 

PLEM 

ENTARY 

QUESTI 

DELE 

TE F 

I LE?=E 

LEMENT ( 

&DF , 

EQ, Y 



DF PATHN 

AME = a$ 

EX$IP 
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An example of the .EXIT primitive used in a command procedure is as follows: 

.PROC EXCEXAMPLE PR0C)=0, 

INPUT PATHNAME = ACNM("a)$EX$IP''), 

OUTPUT PATHNAME=ACNM("a$EX$OP") , 

DISPLAY OR COPY?=ELEMENT(D=D,C=C) (DISPLAY) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$0P="&0UTPUT PATHNAME" 

.IF &DISPLAY,EQ,D 

SF FILE=a$EX$IP 

.EXIT 
. ENDI F 

CC IAN=a$EX$IP,0AN=a$EX$0P 
.PROMPT (SUPPLEMENTARY QUESTION), 

DELETE FILE?=ELEMENT(Y=Y,N=N)(NO) 

.IF &DF,EQ,Y 

DF PATHNAME=a$EX$IP 

. ENDI F 
. EOP 

If the following statement from this example Is true: 

. IF &DISPLAY,EQ,D 

then the SF command procedure is bid to display the file represented by the synonym $EX$IP. The 
.EXIT primitive then terminates the execution of the EX command procedure. If the .IF comparison 
is false, execution of the command procedure continues with the primitives and commands fol- 
lowing the .ENDIF primitive for that .IF comparison. 

3.5.6 .EVAL Primitive 

The .EVAL primitive evaluates a numeric expression, converts the result to decimal or 
hexadecimal ASCII format, and stores it as the value of a specified synonym. The .EVAL primitive 
has the following format: 

.EVAL [mode][ = YES/NO],/7a/r7e = va/ue 

The mode parameter must be the keyword DEC (decimal) or HEX (hexadecimal), to specify the 
conversion mode. If you specify the mode parameter with one of these keywords and enter Y in 
response, the mode specified is the numeric base to which the result is converted, if you enter N, 
the result Is converted into the mode that you did not specify. You can also enter the mode 
parameteY without a Y/N response; in this case, the Y is assumed. The mode parameter is not 
required and automatically defaults to the decimal mode If it is not specified. 

The name parameter specifies the name of the synonym to which the resulting value is assigned. 
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The value parameter is the numeric decimai or hexadecimal integer expression to be evaluated. 
Synonyms can be assigned numeric values and used as operands in the arithmetic expression. 
The valid arithmetic operators are; 

+ unary plus or addition 

- unary minus or subtraction 

* multiplication 

/ division 

The character K can also be used within an expression to denote the constant value 1024. 

The following examples illustrate valid .EVAL primitives. (Assume the synonym THREE has a 
value of 3 and the synonym TWO has a value of 2, the value shown in parentheses to the right of 
the example is the value assigned to the synonym RESULT.) 


.EVAL DEC = Y, RESULT = @THREE*5 - ©TWO (13) 

.EVAL DEC = N, RESULT = @THREE*5 - ©TWO (> D) 

.EVAL DEC,RESULT= ©THREE*5 - ©TWO (13) 

.EVAL RESULT=©THREE*5-©TWO (13) 

.EVAL HEX = Y, RESULT = ©THREE*5 - TWO (> D) 

.EVAL HEX = N, RESULT = ©THREE*5 - TWO (13) 

.EVAL HEX, RESULT =©THREE*5- TWO (> D) 


The .EVAL primitive is useful in establishing counters for loop primitives. Refer to the paragraph 
concerning the .LOOP, .UNTIL, .WHILE, and .REPEAT primitives for an example of its use. 

3.5.7 .LOOP, .UNTIL, .WHILE, and .REPEAT Primitives 

Use the .LOOP, .UNTIL, .WHILE, and .REPEAT primitives to repeat groups of SCI statements 
within command procedures to form a loop. Use the .LOOP primitive to begin a loop and the 
.REPEAT primitive to terminate it. You can use the .UNTIL or .WHILE primitives at any point 
between the .LOOP and .REPEAT primitives. The loop primitives have the following format: 

.LOOP 

.UNTIL op1, relation, op2 

.WHILE op1, relation, op2 

.REPEAT 

The .UNTIL and .WHILE primitives each contain two operands and a relation parameter which is a 
numeric or string compare operation of the type described with the .IF primitive. Op1 and op2 
parameters can be strings, variables, or concatenated strings. 
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The basic structure of a loop in an SCI command procedure is: 
.LOOP 


SCI statements 
.UNTIL or .WHILE 

SCI statements 

.REPEAT 






The .LOOP primitive begins the loop and the .REPEAT primitive ends it. The loop must contain at 
least one .WHILE or .UNTIL primitive at any point within the loop. The SCI statements within the 
loop are executed until the condition of the .WHILE primitive is false or until the condition of the 
.UNTIL primitive is true. When either of these conditions is met, SCI executes the first statement 
following the .REPEAT primitive. 

If multiple .UNTIL and .WHILE primitives are contained within a loop, SCI discontinues the loop 
when the first .UNTIL or .WHILE condition becomes true or false, respectively. SCI then continues 
with execution following the .REPEAT primitive. 

You can also use the .IF primitive within the loop primitives. However, the total depth of nested 
loops with nested .IF statements cannot exceed 32. 

The followfng example contains the loop primitives used within a command procedure. 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM(”a$EX$IP”) , 

OUTPUT PATHNAME=ACNM("a$EX$OP") , 

DISPLAY OR COPY?=ELEMENT(D=D, C=C) (DISPLAY) , 

PRINT THE FILE?=ELEMENT(Y=Y,N=N) (NO) , 

LISTING DEVICE=NAME("a$EX$L”) , 

NUMBER OF COP I ES ? = I NT ( "aSNUM” ) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$OP="&OUTPUT PATHNAME" 

.IF &DISPLAY, EQ, D 

SF FI LE=a$EX$IP 
. EXIT 

.ELSE 

CC IAN=a$EX$IP,OAN=a$EX$OP 
.IF SPRINT, EQ,Y 

.SYN $EX$L=SLIST 

.SYN $NUM="SNUMBER OF COPIES" 

. LOOP 

.UNTIL a$NUM,EQ,0 

PF FI LE=a$EX$IP, L=a$EX$L 
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.EVAL $NUM=a$NUM-1 
.REPEAT 

.SYN $NUM="" 

.PROMPT (SUPPLEMENTARY QUESTION), 

DELETE FILE?=ELEMENT(Y=Y,N=N)(NO) 

.IF &DF,EQ,Y 

DF PATHNAME=a$EX$IP 

. ENDI F 
. ENDI F 
. ENDI F 
. EOP 

In the preceding example, the combination of the .LOOP, .UNTIL, .EVAL, and .REPEAT primitives 
creates a counter mechanism. 

If the .IF comparison of this command procedure is true: 

.IF SPRINT, EQ, Y 

the .SYN primitives are performed, the synonym $EX$L is given the value of the LISTING DEVICE 

response, and the synonym $NUM is given the value of the NUMBER OF COPIES? response. The 

loop is initiated and the .UNTIL primitive compares the value of $NUM with 0. If $NUM is nonzero, 

the Print File (PF) command procedure is bid and prints the file specified by INPUT PATHNAME to 

the LISTING DEVICE specified. The .EVAL primitive then decrements the value of $NUM by one 0 

and the .REPEAT primitive causes the loop to repeat. When the value of $NUM is 0, SCI execution 

continues with the statements immediately following the .REPEAT primitive. 

3.5.8 .SPLIT Primitive 

The .SPLIT primitive splits a value list in two, assigning the first part to one synonym and the 
second part to another. The primitive can have either of the following formats: 

.SPLIT LIST = {list)[,FIRST = /7ame][,REST = name] 
or 

LIST = “string”[, F\RST = name][,REST = name] 

[,CHARACTER = “string”][,POS\T\OM = //?f][, STATUS = name] 

Use the first format to split items separated by commas. Use the second format when the items 
are separated by characters other than commas. 

3.5.8.1 Using the First .SPLIT Format. In the first format, the LIST parameter contains one 
value or a list of values. The first item of the list Is assigned as the value of the synonym name of 
the FIRST parameter and the remainder of the list Is assigned as the value of the synonym name 
Df the REST parameter. 

The operation of the .SPLIT primitive is as follows: 


LIST 

FIRST 

REST 

(A,B,C) 

A 

(B,C) 

A 

A 

null 

null 

null 

null 

((X,Y),Z,G) 

(X,Y) 

(Z,G) 
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Items in the value list must be separated by commas. Parentheses can be used to control the split- 
ting of the list. 

The following example illustrates the first format as used in a command procedure: 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME = ACNM("a$EX$IP") , 

OUTPUT PATHNAME(S)=(ACNM) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$OP="(&OUTPUT PATHNAME)" 

. LOOP 

.WHILE "a$EX$OP",NE,$EX$OP 
.SPLIT LIST="a$EX$OP", 

FIRST=EXOUT, 

REST=$EX$0P 

CC IAN="a$EX$IP",OAN="aEXOUT" 

.REPEAT 

.SYN EXOUT="" 

. EOP 

In this example, the file specified with the INPUT PATHNAME prompt is copied to the file(s) speci- 
fied with the OUTPUT PATHNAME(S) prompt. 

The .SPLIT primitive within the loop determines the current output file to which the input file is to 
be copied. When one copy is complete, .SPLIT updates the current output file to the next output 
file specified in response to the OUTPUT PATHNAME{S) prompt. 

The .WHILE primitive within the loop ensures that the input file is copied to all of the specified 
output files. When all copy processes are complete, execution continues with the primitives and 
commands following the .REPEAT primitive. 

3.5.8.2 Using the Second .SPLIT Format. In the second format, the LIST parameter contains a 
character string. 

The CHARACTER keyword contains a single character or a list of characters. The first occurrence 
of any of the characters in the list causes a.split to occur. What precedes the character and the 
character itself go to FIRST; what remains goes to REST. Specifying by CHARACTER is useful for 
splitting pathnames whose nodes are separated by periods or colons. 

The PCSITICN keyword Is an integer value that specifies a character within the string. The integer 
value determines after which character in the string the split will occur. A 0 or negative value 
causes the FIRST synonym to be null and the REST synonym to contain the entire string. A value 
equal to or greater than the character length of the string causes FIRST to contain the entire string 
and REST to be null. Specifying PCSITICN is useful for splitting files that follow a naming conven- 
tion, where you need to break off a certain number of leading characters and where any character 
could be found at the location of the split. 

When writing the .SPLIT primitive you may indicate CHARACTER, PCSITICN, or both. When 
CHARACTER and PCSITICN are both present, the first condition to be satisfied determines the 
location of the split. 
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The STATUS keyword is a synonym that will be set in one of the following ways: 

• For a split by CHARACTER, the synonym Is set to the character on which the split 
occurred (namely, the character specified). 

• For a split by POSITION, the synonym Is set to the character preceding the split. 

• For a split that does not occur, the synonym Is set to null. 

The following example illustrates the second format as used in a command procedure. The syn- 
onym NAME already has the value DB1. PAYMENT. 

.SPLIT LIST="aNAME", FIRST=DIR, REST=NAME, 

CH AR A GTE R= , STATLJS = CHR 

This command line assigns the value DB1 to the synonym DIR and assigns the value PAYMENT to 
the synonym NAME. CHR, the synonym for the STATUS keyword, is set to 

In the following example, the synonym NAME already has the value ABCDEFG. 

.SPLIT LIST="aNAME",FIRST=PART1, REST=PART2, 

P0SITI0N=3, STATUS=CHR 

This command line assigns the value ABC to the synonym PART1 and assigns the value DEFG to 
the synonym PART2. CHR, the synonym for the STATUS keyword, is set to “C”. 

In the next example, the command line specifies a split by both CHARACTER and POSITION. 

.SPLIT LIST = "aNAME'',FIRST = SITE, CHARACTER = ":'', 

P0SITI0N=8, STATUS=CHR 

This command line breaks the contents of NAME at the first colon or after the eighth character, 
whichever condition is satisfied first. The synonym SITE receives the first part of NAME. Since 
REST is not specified, the second part of NAME is discarded. CHR will be set to either or the 
eighth character of NAME. 

3.5.9 .BID Primitive 

The .BID primitive specifies the execution of a DNOS task. Tasks initiated with the .BID primitive 
share synonyms and logical names with SCI and must execute serially (that is, such tasks can 
only execute at a terminal one at a time). 

The .BID primitive has the following format: 

.BID TASK = name/intlL^NO = /V7t][,CODE = int] 

[,PROGRAM FILE = ac/7/77][,PARMS = (string. ..stnng)][,UT\L\TY] 
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The TASK = namelint parameter is required and identifies a task located in a program file. The 
value can be specified as a name or as an integer. The LUNO = int parameter is optional and speci- 
fies a LUNO assigned to the program file. The default value for LUNO is the LUNO assigned to the 
.S$SHARED program file. CODE is an optional value containing an integer from 0 through 255 that 
can be accessed by the task as a binary value. The default value for CODE is 0. PROGRAM FILE is 
the access name of the program file. If you specify PROGRAM FILE, you cannot specify LUNO. 
PARMS Is optional and contains a list of character strings, separated by commas, that can be 
accessed by the task. UTILITY specifies that the program which is to be bid exists on the .S$UTIL 
utilities program file. If you specify UTILITY,you cannot specify either LUNO or PROGRAM FILE. 
SCI transfers control to the task upon encountering the .BID primitive. When the task terminates, 
SCI processes the next statement in the procedure. 

The following example illustrates the .BID primitive: 

.PROC EXCEXAMPLE PR0C)=0, 

INPUT PATHNAME = ACNM(''a$EX$IP") , 

OUTPUT PATHNAME<S)=(ACNM) , 

PRINT THE FILE?=ELEMENT(Y=Y,N=N) (NO) 

.SYN $EX$IP=”&INPUT PATHNAME" 

.SYN $EX$0P="&0UTPUT PATHNAME" 

.SYN $EX$P="&PRINT" 

.BID TASK=>40 , PARMS= ("a$EX$ I P" , "a$EX$0P" , "a$EX$P") 

. EOP 

In this example, the .BID primitive bids a task with a task ID of >40 residing In the .S$SHARED 
program file. 

The values for synonyms $EX$IP, $EX$OP, and $EX$P are set to be the responses entered for the 
INPUT PATHNAME, OUTPUT PATHNAME(S), and PRINT THE FILE? prompts, respectively. The 
task uses these synonym values as parameters during execution. 

3.5.10 .DBID Primitive 

The .DBID primitive specifies the execution of a task as a background task in a suspended state. 
The .DBID primitive enables you to debug the command processor using the SCI debugger. A 
snapshot of synonyms and logical names is taken when a task is executed by .DBID, allowing you 
to execute another foreground task concurrently. 

The .DBID primitive has the following format: 

.DBID TASK = namellnt[,LUNO = /A7f][,CODE = int] 

[,PROGRAM FILE = ac/7/77][,PARMS = (sfr//7Sf...sfr/r7g)][,UTILITY] 
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The parameter definitions of the .DBID primitive are identical to the .BID primitive parameters. The 
following example illustrates the .DBID primitive as it is used in a command procedure. 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME = ACNM("a$EX$IP") , 

OUTPUT PATHNAME(S)=(ACNM) , 

PRINT THE FILE?=ELEMENT(Y=Y,N=N) (NO) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$0P="&0UTPUT PATHNAME" 

.SYN $EX$P="&PRINT" 

.DBID TASK=USERTASK, PARMS=("a$EX$IP" ,"aEX$0P" , "a$EX$P") , 
PROGRAM FILE=.USERPROG 

. EOP 

The .DBID example bids the task by name, USERTASK, from the program file .USERPROG and 
executes as a background task in suspended state, performing the same functions as the .BID 
primitive example. 

3.5.11 .QBID Primitive 

The .QBID primitive specifies the execution of a task as the background task of a terminal. In the 
interactive mode, SCI processes the next input command after initiating execution of the task and 
the task executes concurrently. In the batch mode, SCI Is suspended until the task terminates. A 
snapshot of synonyms and logical names is taken when a task is executed by .QBID. 

The .QBID primitive has the following format: 

.QBID TASK = /7ame//>7f[,LUNO = />7f][,CODE = int] 

[, PROGRAM FILE = acnm][, FARMS = {string. ..strmg)]l\JJ\L\TY] 

The .QBID and .DBID primitive parameter definitions are identical. The following example uses the 
.QBID in a command procedure; 

.PROC EXCEXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM("a$EX$IP"), 

OUTPUT PATHNAME(S)=(ACNM) , 

PRINT THE FI LE?=ELEMENT(Y=Y,N=N) (NO) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$0P="&0UTPUT PATHNAME" 

.SYN $EX$P="&PRINT" 

.QBID TASK=USERTASK, PARMS=("a$EX$IP", "QEXSOP", "a$EX$P") , 
PROGRAM F I LE= . USERPROG 

. EOP 

This example bids the task (USERTASK) from the program file .USERPROG and executes as a 
background task at the terminal, performing the same functions as the .BID primitive example. 

3.5.12 .RBID Primitive 

The .RBID primitive bids several system utilities. The primitive must be used with great care, so 
that system utilities are not affected. Refer to the DNOS SCI and Utilities Design Document for 
further information concerning the .RBID primitive. 
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3.5.13 .DATA and .EOD Primitives 

The .DATA primitive copies data directly to a file from the command input stream. You must use 
the .EOD primitive to terminate the data stream. The .DATA primitive has the following format: 

.DATA [acr7m]I,EXTEND[ = YES/NO]][,SUBSTITUTION[ = YES/NO]] 

[,REPLACE[ = YES/NO]] 

The acnm specifies the file or device to which the data is to be copied. If the acnm is not specified, 
the Terminal Local File (TLF) is assumed. Since the TLF is displayed when the command proce- 
dure completes execution, the .DATA primitive can be used to send status and error messages to 
the bidding terminal and place debugging statements in a procedure to track the path of 
execution. 

There are three parameters (EXTEND, SUBSTITUTION, and REPLACE) which affect the copying 
process. The EXTEND parameter specifies whether the data file is to be opened extended. This 
allows you to concatenate several data streams under one pathname. If you do not specify the 
EXTEND parameter, the default is taken and the data file is not opened extended. If you use the 
TLF, the file is always opened extended. 

The SUBSTITUTION parameter specifies whether textual substitution is to be done on the data 
stream before it is copied to the specified acnm. Textual substitution causes the appropriate 
values to be substituted for field prompts preceded by ampersands (&) and synonyms preceded by 
at signs (@). Multiple blanks are also compressed to a single blank unless they are enclosed by 
quotation marks (“). Any characters after an exclamation mark (!) and any comment lines are omit- 
ted. If you do not specify SUBSTITUTION, the default is taken and textual substitution is not 
performed. 

You can use the REPLACE parameter in a data stream to replace an existing file specified by 
acnm. If you do not specify REPLACE, the default is taken and file replacement is performed. If 
you use the TLF, the REPLACE parameter is ignored. If you specify both EXTEND and REPLACE, 
EXTEND is used if REPLACE = NO. 

Following is an example of the .DATA and .EOD primitives: 

.PROC EXCEXAMPLE PR0C)=0, 

INPUT PATHNAME = ACNM("a$EX$IP''), 

OUTPUT PATHNAME= (ACNM) 

.SYN $EX$I P="&INPUT PATHNAME" 

.SYN $EX$0P=" (&0UTPUT PATHNAME)" 

. LOOP 

.WHILE "a$EX$0P",NE,$EX$0P 
.SPLIT LIST="a$EX$OP", 

FIRST=EXOUT, 

REST=$EX$0P 

cc iAN="aa$Ex$iP",OAN="aaExouT" 

. DATA 

COPY COMPLETED 
. EOD 
.REPEAT 
. EOP 
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In this example, the .DATA and .EOD primitives are used to output the foiiowing message to the 
TLF when an input fiie has been copied to a specified output file: 

COPY COMPLETED 

In the previous example, if the message was to be appended to the contents of a file (for instance, 
.KCOUT), the following EXTEND option must be specified for the .DATA primitive: 

.DATA . KCOUT, EXTEND = YES 
COPY COMPLETED 
. EOD 


3.5.14 .STOP Primitive 

The .STOP primitive terminates execution of SCI and has the following format: 

.STOP {TEXT = string][, CODE = int] 

In batch mode, the string specified by the TEXT parameter is optional and can be used to create a 
message to send to the interactive SCI in place of the message BATCH SCI HAS COMPLETED. 
The CODE parameter is optional and is used to set the synonym $$BC in the synonym table of the 
bidding task (SCI) when a batch stream completes. The $$BC synonym is deleted by SCI when a 
background task is initiated. The TEXT and CODE parameters are ignored when SCI is not in batch 
mode. 

You cannot enter the .STOP primitive interactively at a terminal If any of the following operations 
are in progress at the terminal: 

• Text editing 

• Debugging 

• Execute System Configuration Utility (XSCU) session 

• Background activity 

When the .STOP primitive is processed, SCI execution does not terminate immediately. The M$01 
procedure executes, saving synonyms and logical names (in the same way the Q command does). 
Refer to the System Command Interpreter (SCI) Reference Manual for details about the M$01 
procedure. 

The following example illustrates the interactive use of the .STOP primitive: 

.PROC LOCTERMINAL IS LOGGING OFF)=0 IFULL NAME DISPLAYED 

.SVC D=(0200,20) ITIME DELAY SVC 

.STOP ITERMINATE SCI 

. EOP 

In this example, the .STOP primitive is used within a command procedure to stop SCI and log off 
the terminal after a short time delay. (The .SVC primitive is explained later in this section.) 
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Following is an example of a command procedure written to stop a batch stream: 

SBATCH (STOP BATCH EXECUTION), 

TEXT=*STRING, CODE=*INT 

.IF a$$M0, NE, 0 

. EXIT 

.ENDIF 

SDT 

.STOP TEXT = "&TEXT'' , C0DE = "&C0DE" 

Note that during the processing of .STOP, the value of $$CC is changed. Therefore, if you use 
$$CC in the CODE = portion of .STOP, the vaiue wiii be from .STOP processing, not from previous 
activity. 

3.5.15 .USE Primitive 

The .USE primitive specifies alternate procedure libraries to be used by SCi. The .USE primitive 
has the following format: 

.USE [pathname 1[, pathname 2[, pathname 3[, pathname 4 [pathname 5]]]]] 

From one to five pathnames follow the .USE statement. Each pathname specifies a command 
library. Once invoked, the menus and command procedures are taken from these libraries. If a 
menu or command procedure is not found after searching the library specified by pathname 1, 
then the library specified by pathname 2 is searched, and so on. The .USE primitive remains in 
effect until it is replaced by another .USE or until a log-off/log-on sequence occurs. 

To revert to the standard system library, specify a .USE primitive with no operands. In this case, 
the default value .S$CMDS Is taken as pathname 1 and the remaining pathnames are nuli. 

The synonym $$CL is set each time a .USE is issued. The vaiue assigned to $$CL is the string of 
libraries specified in the .USE statement. When installing a command procedure, SCi places the 
command definition into the directory specified by pathname 7.0ne of the pathnames must con- 
tain the main menu specified by the .OPTION primitive discussed in subsequent paragraphs. 


NOTE 

If the main menu cannot be found after executing the .USE primi- 
tive, a warning message is output. You must execute another .USE 
primitive to specify the correct command procedure directory con- 
taining the main menu. 
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The .USE primitive affects oniy the SCi session in which it was executed. Every SCI session 
begins with the system library .S$CMDS as the default library. A .USE primitive executed from an 
interactive terminal has no effect on any batch SCI executed from the terminal. 

The following example illustrates the .USE primitive for the interactive mode: 

[] .USE .USERLIB, .S$CMDS 

This statement enables you to access the command procedures in the .USERLIB library and the 
.S$CMDS system library. 

In the following example, the .USE primitive is used in a command procedure to access com- 
mands in the directory .USERLIB. When the .PROC primitive is encountered, SCI installs the EX 
(Example Proc) command procedure into the .USERLIB library. 

.USE .USERLIB, . SSCMDS 

.PROC EX(EXAMPLE PROC)=0, 

INPUT PATHNAME=ACNM("a$EX$IP") , 

OUTPUT PATHNAME(S)=(ACNM) , 

PRINT THE FILE?=ELEMENT(Y=Y,N=N) (NO) 

.SYN $EX$IP="&INPUT PATHNAME" 

.SYN $EX$OP="(&OUTPUT PATHNAME)" 

.SYN $EX$P="&PRINT" 

.BID TASK = USERTASK, PARMS=("a$EX$IP", "a$EX$OP","a$EX$P") , 

PROGRAM FILE=.USERPROG 

. EOP 

3.5.16 .OPTION Primitive 

The .OPTION primitive enables you to modify some basic interface characteristics of SCI to suit 
your local language or application requirements. 

The .OPTION primitive has the following format: 

.OPTION [PROMPT[ = sfr/V?flf]][,MENU[ = A7a/77e]][, PRIMITIVES! = YES/NO]] 

[,LOWERCASE[ = YES/NO]] 
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The parameter definitions are as foiiows: 


Keyword Assigned Value 

PROMPT An aiternative prompt charac- 

ter string which must be iess 
than 50 characters in iength. 


MENU Main menu name. (SCi wiii 

automaticaiiy prefix the spec- 
ified menu with M$ to obtain 
the menu fiie name in your 
PROG iibrary). 


PRiMiTiVES YES or NO 


LOWERCASE YES or NO 


Function 

Enables you to specify the 
SCi prompt. The default 
SCI prompt is [ ] repre- 
sented by the ASCII codes 
>7Band>7D. 

Enables you to specify your 
own main menu which is 
displayed after each menu 
display cycle in VDT mode. 
The default SCI menu is 
named LC. 

Enables you to allow or 
disallow the use of primi- 
tives at the primary level. In 
the case of interactive SCI, 
you are allowed or disal- 
lowed to use primitives at 
the keyboard. In batch SCI, 
you are either allowed or 
disallowed the use of primi- 
tives in the batch stream. 
The default is YES. 

Enables you to allow or 
disallow lowercase to 
uppercase mapping of 
input to SCI. The default is 
NO. Use of the LOWER- 
CASE option does not 
apply to batch stream pro- 
cessing or the following 
SCI command processors; 

CVD DCOPY 

INV MS 

XANAL MVI 
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The following example shows the use of the .OPTION primitive to display the station number. 
MYMENU is a user constructed menu which is to be displayed, replacing the SCI main menu. 

.PROC NP(NEW PROMPT PROC) 

.OPTION PROMPT="STa$$ST",MENU=MYMENU, PRIMITI VES=YES 
. EOP 

The synonym $$ST in this example represents the station number of the user’s terminal. 

In the following example, the .OPTION primitive Is used to select the EDIT menu found in 
.S$CMDS.M$EDIT for display at each menu display cycle of SCI. This command also disables 
primitives at the primary level. 

.OPTION MENU=EDIT, PRIMITI VES=NO 

The next example illustrates the use of the .OPTION primitive to select a user-constructed menu 
(PROPRE) found in the user command library with the file name .M$PROPRE, replacing the SCI 
main menu displayed. This command also enables the use of lowercase characters as inputs to 
SCI. 


.OPTION MENU=PROPRE, LOWER CAS E= YES 
3.5.17 .MENU Primitive 

The .MENU primitive causes SCI to display a specified menu the next time SCI is in command 
mode. The .MENU primitive has the following format: 

.MENU [menu name] 

There are three variations of the menu name parameter: 

• No menu specified — The use of a .MENU with no menu specified causes screen con- 
tents to remain unchanged in the next menu cycle. 

• Menu name — If you specify a menu name (one through six alphanumeric characters), 
SCI will display the menu in the next menu cycle, whether the station is in TTY or VDT 
mode. SCI appends the characters M$ at the beginning of the name to obtain the file 
name within your command procedure library file where the menu resides. 

• *Menu name — If you specify a menu name preceded by an asterisk, the menu is dis- 
played only if the station is in VDT mode. 

An equivalent alternative to the .MENU primitive is the slash (/) symbol. It is defined as follows: 

/ is equivalent to .MENU 

/DEV is equivalent to .MENU DEV 

/*DEV is equivalent to .MENU *DEV 
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The following example illustrates the .MENU primitive: 

.PROC NMCNEW MENU PROC) 

.MENU MYMENU 

. EOP 

This example specifies MYMENU to be displayed on the terminal. SCI searches the command 
library for the file M$MYMENU and displays the menu in that file on the next menu display cycle. 

3.5.18 .SHOW Primitive 

The .SHOW primitive displays the contents of a specified file or files to an interactive terminal or 
batch listing file. The .SHOW primitive has the following format: 

.SHOW filename[,filename.. .filename] 

where: 

filename is the name of a file. 

The .SHOW primitive cannot display program files, image files, or directories. 

.SHOW is equivalent to the Show File (SF) command. The function keys used with the SF com- 
mand are applicable to the .SHOW primitive. Refer to the SF command in the System Command 
Interpreter (SCI) Reference Manual for descriptions of the function keys. 

The following example illustrates the .SHOW primitive used In the SF command procedure: 

.PROC SF(SH0W FILE)=0, 

INPUT FILENAME=ACNM("a$SF$IP") 

.SYN $SF$IP="&INPUT FILENAME" 

.SHOW aa$SF$ip 

. EOP 

In the previous example, the .SHOW primitive displays the file specified as the response to the 
INPUT FILENAME prompt. The .SHOW primitive is not limited to the SF command procedure; it 
can be used in any command procedure. 

3.5.19 .SVC Primitive 

The .SVC primitive allows you to issue supervisor calls (SVCs) from the SCI procedure language. 
The format of the .SVC primitive is as follows: 

.SVC [$name ] DATA/ BYT E/TEXT = value(s)...[$name ] DATA/ BYTE/TEXT = value(s) 

The optional $name parameter is a synonym that can be used to retrieve information returned to 
the SVC call block by DNOS. The DATA, BYTE, and TEXT parameters enable you to describe the 
SVC call block with value(s) as they might appear in assembly language. The execution of this 
command causes SCI to build the supervisor call block and issue the SVC. The synonym $$CC is 
set to >00 If the SVC completes normally; otherwise, SCI sets an error condition enabling the 
command procedure to test for abnormal cases via the $$CC and $$MN synonyms. The $$CC and 
$$MN synonyms are described elsewhere in this manual. 
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There are some SVCs which cannot be used with the .SVC primitive. These limitations are signifi- 
cant and are described in Table 3-8. 

To use the .SVC primitive, perform the following steps: 

1. Determine the SVC to be issued. Make sure that it does not fall into any of the catego- 
ries of disallowed SVCs. 

2. Format the SVC call block using the DATA, BYTE, and TEXT parameters. After each 
parameter, insert an equals sign ( = ). 

a. If the SVC definition requires a pointer to a text string, replace the pointer (which is 
always a DATA value) with the text. The following example illustrates this use in 
the System Log SVC when written in assembly language: 

SVCB DATA >2100 

DATA 0 

DATA POINTER 
DATA 0 

POINTER BYTE 20 

TEXT 'TEXT FOR LOG MESSAGE' 

The following is an example of .SVC primitive used to issue the System Log SVC: 

.SVC DATA=>2100, 

DATA=0, 

DATA="TEXT FOR LOG MESSAGE", 

DATA=0 

SCI realizes the text supplied for the pointer Is not a data value and stores the text 
string with the preceding byte length count. A pointer to this string is generated by 
SCI and placed in the SVC block. 

b. If the SVC definition requires text within the call block, you must declare the field 
length of the text. To do this, place the field length within parentheses before the 
text. Following Is an example of this use in the Map Task Name to ID SVC when 
written In assembly language: 

SVCB DATA >3100 

DATA 0 

TEXT SCI990 
DATA OFFOO 
DATA 0 
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The following is an example of the .SVC primitive used to issue the Map Task 
Name to ID SVC: 

SVC DATA=>3100, 

DATA = 0, ■ 

TEXT=(8)SCI990, 

DATA=0FF00, 

DATA=0 

This example causes the field to be blank filled with the text left-justified. 

3. If you are using a list of DATA or BYTE values, enclose the list in parentheses, as shown 
beiow for the System Log Message SVC; 

.SVC DATA=(>2100,0, "MESSAGE FOR SYSTEM LOG",0) 

A list of TEXT is not ai lowed. 

4. Information returned by DNOS is retrieved from the call block by placing a label name 
before the DATA, BYTE, or TEXT field of interest. The labei name must begin with a $, as 
shown below when issuing the Map Task Name to ID SVC using the .SVC primitive: 

.SVC DATA=(>3100,0) , 

TEXT=(8)SCI990, 

BYTE=0FF, 

STASKID BYTE=0, 

DATA=0 

After the SVC is issued, SCI assigns the hexadecimal ASCII value of the DATA or BYTE 
parameter or the text string of the TEXT parameter to the system $TASKID. If a list of 
values was specified as the DATA or BYTE parameter, the synonym is assigned the first 
item of the list. Such synonyms are assigned whether or not an error occurs when the 
SVC is executed. 




2270510-9701 


3-41 



Extending SCI 


The following examples Illustrate uses of the .SVC primitive. 

The first example uses the .SVC primitive to cause a time delay of 100 system time units, as shown 
below: 


.SVC DATA=(0200,100) 

The second example uses the .SVC primitive to kill a task with a run ID value equivalent to the 
value of the synonym $$RI. The state of the task terminated is converted to ASCII (base 16) and the 
synonym $STATE is assigned that value. 

-SVC DATA=03300, 

BYTE=(a$$RI,0) , 

$STATE BYTE=(0, 0,0,0) 

In the third example, the .SVC primitive is used to assign a global LUNO to the directory .S$CMDS 
and return the LUNO that was assigned as the value of $$LU. A special feature of the DATA field is 
shown here. If any element in the DATA list cannot be converted into a number, SCI allocates 
memory and copies the element as a string (preceded by a byte count), placing the address of the 
string in the SVC block. 

.SYN TYPE=02000 ! TYPE IS DIRECTORY FILE 

.SYN SCOPE=01000 ! THE LUNO SCOPE IS GLOBAL 

.SVC DATA=0, 

BYTE=>91 , 

$$LU BYTE=0, 

DATA=(0,0,0,0,0,0,aTYPE + aSCOPE + 0400,0,0) , 

DATA=. SSCMDS 

The advantages of the .SVC primitive as opposed to bidding a separate task to perform the SVC 
are as follows: 

• Efficiency — The overhead Involved to bid a task is avoided. 

• Generality — Some functions are supported by the operating system and are not avail- 
able in the standard set of SCI commands. 
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Table 3-8. Disallowed SVCs for .SVC Primitive 


SVC Type 


Restrictions 


Privileged SVCs 


External Data Blocks 


Since SCI is not a privileged task, privileged SVCs cannot be 
issued. DNOS enforces this limitation. Refer to the DNOS 
Supervisor Call (SVC) Reference Manual to determine if the 
desired SVC is privileged. 

SVCs that use external data blocks (other than text string for- 
mat for input) are not allowed. SCI enforces this limitation and 
disallows the following SVCs: 


SVC Subopcode Function 


>00 >05 

>09 
>0A 
>0B 
>0C 
>10 

>40->52 

>03 

>0A 

>0B 

>0C 

>0D 

>1C 

>1D 

>3B 

>3F 

>45 

>46 

>47 

>4C 


Read Characteristics 
Read ASCII 
Read Direct 
Write ASCII 
Write Direct 
Rewrite 

All KIF Subopcodes 
Get Date and Time 
Convert Binary to 
Decimal 

Convert Decimal to 
Binary 

Convert Binary to Hexa- 
decimal 

Convert Hexadecimal to 
Binary 
Put Data 
Get Data 

Initialize Date and Time 
Retrieve System Data 
Encrypt Data 
Decrypt Data 
Log Accounting Entry 
Return Code Processor 
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Table 3-8. Disallowed SVCs for .SVC Primitive (Continued) 


SVC Type 


Restrictions 


Special SVCs SVCs that might jeopardize the internal functioning of SCI are 

not allowed. SCI enforces this limitation and disallows the fol- 
lowing SVCs: 


SVC 

Function 

>01 

Wait for I/O 

>04 

Terminate Task 

>0F 

Abort I/O by LUNO 

>10 

Get Common 

>12 

Get Memory 

>13 

Release Memory 

>14 

Load Overlay 

>1B 

Release Common 

>40 

Segment Manager 

>43 

Name Manager 


3.6 SCi PRiMiTiVE BATCH STREAM EXAMPLE 

The following example uses SCI primitives in a batch stream to install a program in a program file. 
The first command of every batch stream should be the Batch SCI (BATCH) command and the last 
command should be the End Batch SCI (EBATCH) command. The BATCH command clears un- 
necessary synonyms and EBATCH indicates that there are no more commands to be processed in 
the batch stream. 
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EXAMPLE 


BATCH LS=YES 


* 


* 


* 


ASSEMBLE, LINK AND INSTALL THE EXAMPLE TEST TASK 
ASSUME: SOURCE = SOURCE DIRECTORY 

OBJECT = OBJECT DIRECTORY 
LISTING = LISTING DIRECTORY 
PROG = PROGRAM FILE 
CONTROL = LINK CONTROL DIRECTORY 
LINK = LINKED OUTPUT DIRECTORY 
LINKMAP = LINKMAP DIRECTORY 


* ASSEMBLE EXAMPLE SOURCE MODULES: EXAMPLE01, EXAMPLE02 

* 

XMA SOURCE=SOURCE. EXAMPLE01 , OB J ECT=OBJ ECT . EXAMP LE01 , 
L.ISTING = LIST. EXAMPLE01 , OPT I ON S= ( X RE F , DUN , BUN , TUN) 

EC 

XMA SOURCE=SOURCE. EXAMPLE02, OB J E CT=OB J E CT . EXAMP LE02 , 
LISTING = LIST. EXAMPLE02, OPT I ON S= < X R E F , DUN , BUN , TUN ) 

EC 


* IF NO ASSEMBLY ERRORS THEN LINK THE EXAMPLE TASK 

* 

•IF a$E$C,EQ,0 

XLE CONTROL=CONTROL. EXAMPLE, LINKED OUTPUT= L I N K . EXAMP LE , 

LISTING=LIN KM AP. EXAMPLE 
EC 

.ENDIF 

* 

* IF NO ERRORS OCCURRED DURING THE LINK 

* DELETE THE CURRENT TASK 

* 

.IF a$E$C,EQ,0 

DT PROGRAM FILE=PROG, TASK NAME=EXAMPLE 

. ENDIF 

★***★*★****★**★★★***★*★**★*★★★***★★★***★***★★***★*******★★*★**★**★**** 

* 

* IF NO ERRORS OCCURRED DELETING THE OLD TASK 

* INSTALL THE NEW PROGRAM 

* 

.IF a$E$C,EQ,0 

IT PROGRAM FILE=PROG, OBJECT PAT HN AME= L I N K . EX AMP LE 

EC 

. ENDIF 

**********★★★**★**★***★*★**★*★■******★**★★*********★★********★**★****** 

* 

* INSTALLATION OF EXAMPLE PROGRAM COMPLETE 

* 

EBATCH TEXT=''INSTALLATION COMPLETE, ERRORS=a$E$C" , CODE=a$E$C 
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* IF NO ERRORS OCCURRED DELETING THE OLD TASK 

* INSTALL THE NEW PROGRAM 

* 

.IF a$E$C,EQ,0 

IT PROGRAM FILE=PROG, OBJECT PATHN AME= L I N K . EX AMP LE 

EC 

•ENDIF 

* 

* INSTALLATION OF EXAMPLE PROGRAM COMPLETE 

* 

EBATCH TEXT="INSTALLATION COMPLETE, ERR0RS=3$E$C" , CODE=a$E$C 


3.7 ERROR PROCESSING FOR PRIMITIVES 

If SCI encounters a syntax error within the parameters of a primitive in a command procedure, the 
command procedure execution aborts. If the error occurs on a primitive that is in a batch stream, 
the batch stream terminates at the point of error. 

If the destination file cannot be accessed for the .PROC or .DATA primitives, SCI scans until it 
encounters an .EOP or .EOD primitive. SCI then sets the synonym $$CC to an error condition and 
continues processing. For example, if a batch stream is executed and the destination file for a 
.PROC or .DATA primitive is not accessible, SCI continues to execute the remaining procedures. 


3.8 COMMAND PROCEDURES AND COMMAND PROCESSORS 

In addition to the command procedures and command processors supplied with the DNOS operat- 
ing system, the system programmer can write new procedures and processors which fulfill user 
requirements. The rules of the SCI language syntax and the SCI primitives discussed earlier in this 
section are applied when writing new procedures and processors. The following paragraphs dis- 
cuss the design of command procedures and command processors and the various options 
available. 

3.8.1 Command Procedure Design 

A command procedure is a sequence of statements that is executed each time you issue an SCI 
command. The command procedure Is composed of SCI statements including commands, primi- 
tives, and menu invocations executable by SCI. 

Command procedures are designed to: 

• Collect responses to field prompts 

• Assign values to synonyms to be used by this or other procedures 

• Call command processors and/or other command procedures 
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Procedures can collect responses to field prompts and perform various actions such as compari- 
sons with the .IF primitive. For example, the Install Task (IT) command tests the response to the 
field prompt ATTACHED PROCEDURES? and may Issue additional field prompts, depending on 
the result of the comparison. 

A synonym can be enclosed In parentheses after the field prompt type and defined as the initial 
value of the field prompt in a command procedure, as In the following: 

.PROC SFCSHOW FILE), 

FILE PATHNAME = *ACNM(*'a$SF$P") 

.SYN $SF$P="&FILE PATHNAME" 

.IF "&FILE PATHNAME", NE, "" 

.SHOW a&FILE PATHNAME 
.ENDIF 

. EOP 

In this procedure, the value of the synonym $SF$P is the initial value for FILE PATHNAME. The ® 
sign preceding the synonym designates the synonym value. When you first log on the system, 
$SF$P has no assigned value and the field prompt has no initial value displayed. After you execute 
the first SF, the synonym is assigned the value which Is entered as the initial value for FILE 
PATHNAME In subsequent SF executions. 

In addition to assigning synonyms within the command procedure, the use of a synonym as an 
initial value enables the command procedure to recall the synonym with its last assigned value. 
Initial values are not required to be synonyms in command procedures; they can be numbers or 
strings. For initial values that are synonyms, values are not required to be assigned for the 
synonyms. For example, if the synonym .FILE has no value assigned, the character string FILE fol- 
lowing the . sign is assigned as the value. 


After all references are resolved, if the initial value for a field prompt begins with a $ sign, then the 
field prompt is given a null value (not the string that begins with the $ sign as the initial value). 

The ability of one procedure to call other procedures offers you several advantages. It allows one 
procedure to perform a simple field prompt test and branch to other command procedures, thus 
simplifying user input. As an example of such a procedure, the CF command can be written as 
follows: 

.PROC CF (CREATE FILE - SEQ, REL, KEY, DIR, PRO, IMG), 

FILE TYPE=ELEMENT<SEQ, REL, KEY, DIR, PRO, IMG) (SEQ) 

* 

.IF "a$$M0", EQ, 0 

MSG T="ERROR: USE SPECIFIC FILE TYPE CREATE IN BATCH" 
.ELSE 


. I F 
CFSEQ 
. ENDIF 

"&FI LE 

TYPE", 

EQ, 

SEQ 

. IF 
CFREL 

"&FI LE 

TYPE", 

EQ, 

REL 


. ENDIF 
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. IF 
CFKEY 
. ENDI F 

"SFI LE 

TYPE", 

EQ, 

KEY 

. IF 
CFDIR 
. ENDIF 

"SFI LE 

TYPE", 

EQ, 

DIR 

. I F 
CFPRO 
. ENDIF 

"SFI LE 

TYPE" , 

EQ, 

PRO 

. I F 
CFIMG 
. ENDIF 
. ENDIF 

"SFI LE 

TYPE", 

EQ, 

IMG 


. EOP 

In the batch mode of SCI operation, the top level procedure of a nested command definition must 
recognize all field prompts of the command, including those used by the nested procedure. In the 
following example, the field prompt OBJECT ACCESS NAME is used in the nested procedure and 
must be specified in the top level procedure. 

.PROC RUNCEXECUTE APPLICATION PROGRAM), 

LANGUAGE (COBOL, PA SCAD =N AM E, 

! XCP PROMPT 

OBJECT ACCESS NAME 
! CHECK FOR BATCH MODE 

.IF "a$$MO",EQ,0 
.IF "SLANGUAGE", EQ, "COBOL" 

XCP OBJECT ACCESS N AME="&OB J E CT ACCESS NAME" 

. ENDI F 
. EXIT 
. ENDI F 

! INTERACTIVE MODE 

.IF "SLANGUAGE", EQ, "COBOL" 

XCP 
. EXIT 
. ENDI F 

.IF "SLANGUAGE", EQ, "PASCAL" 

XPT 
. EXIT 
. ENDI F 

. EOP 
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The top-level procedure RUN calls the Execute COBOL Program (XCP) command; however, the 
RUN procedure is divided into two parts. The first part of the RUN procedure is used for batch 
execution. The XCP command is calied with the appropriate field prompt values, assuming all 
synonyms are assigned correct vaiues prior to execution. 


NOTE 

Synonyms can be set by previous command procedures in a batch 
stream. Therefore, you must take appropriate action so that the cor- 
rect synonyms are used. 


The second part of the RUN procedure is used for interactive mode. When the XCP command is 
calied, field prompt values are not assigned so that they wili be prompted at the terminal. 


NOTE 

As soon as a procedure terminates, its field prompts and their 
values are destroyed. 


The following examples show how to call the RUN procedure in batch and interactive modes. 
Example of batch mode: 

RUN LANG=C0B0L, OBJ =0. TEMP 
Example of interactive mode: 

[]RUN 

EXECUTE APPLICATION PROGRAM 

LANGUAGE: COBOL 

EXECUTE COBOL PROG R AM<V E R S I ON : 3 . 3 . 1 81196> 

OBJECT ACCESS NAME: O.TEMP 
MESSAGE ACCESS NAME: 

SWITCHES: 00000000 
FUNCTION KEYS: NO 

If a command procedure uses the .PROMPT primitive in the interactive mode to gather responses 
from additional screens of prompts, special provisions must be made for batch execution. The 
procedure must include DEFAULT type prompts for all .PROMPT screens along with the first 
screen of prompts. For example, the following CIO command procedure includes DEFAULT types 
for the RESOURCE TYPE and PROCESS ASSIGNS? prompts that are to be displayed in the second 
screen. 
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CIC(CREATE IPC CHANNEL)=2, 

CHANNEL PATHNAME = ACNM, 

OWNER TASK PROGRAM FILE= ACNM, 

OWNER TASK NAME OR ID = N AME / R ANG E ( 0 , 0 F F ) , 

CHANNEL TYPE = E LEMENT ( S=S YMM ETR I C , 

M = MASTER/ SLAVE) (SYMMETRIC) , 

CHANNEL SCOPE = E LEMENT ( G=G LOB A L , 

T=TASK, J=JOB) (GLOBAL) , 

MAXIMUM MESSAGE LENGTH = RANGE (1 , 03000) (1 00) , 
SHARED CHANNEL ACCESS? = ELEMENT (Y = YES , N = NO) (YES) , 
RESOURCE TYPE = D E F AU LT ( C H AN ) , 

PROCESS ASSIGNS? = DEFAULT(NO) 

.IF "&CHANNEL TYPE" , EQ , MASTER/S LAVE 
.PROMPT(MASTER/SLAVE CHANNEL ATTRIBUTES), 

RESOURCE TYPE = INT 

PROCESS ASSIGNS?=ELEMENT(Y=YES,N=NO) (NO) 


(procedure continues) 

The field prompts from .PROMPT screens are defined without type information. This allows the 
use of a single command procedure in both interactive and batch modes, but prompt the field 
prompts in groups in interactive mode. 

The following examples show how to use the CIO procedure in batch mode and interactive mode. 
Example of batch mode: 

CIC CHANNEL PATHNAME= . MKC . REPORT , 

OWNER TASK PROGRAM F I LE= . MKC . COMP I LE , 

OWNER TASK NAME OR ID=TAX, 

CHANNEL TYPE=MS, 

CHANNEL SC0PE=T, 

MAXIMUM MESSAGE LENGTH=100, 

SHARED CHANNEL ACCESS?=YES, 

RESOURCE TYPE=CHAN, 

PROCESS ASSIGNS?=NO 

Example of interactive mode: 

[]CIC 

CREATE IPC CHANNEL 

CHANNEL PATHNAME: .MKC. REPORT 
OWNER TASK PROGRAM FILE: .MKC. COMPILE 
OWNER TASK NAME OR ID: TAX 
CHANNEL TYPE: MS 
CHANNEL SCOPE: TASK 
MAXIMUM MESSAGE LENGTH: 100 
SHARED CHANNEL ACCESS: YES 
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MASTER/SLAVE CHANNEL ATTRIBUTES 
RESOURCE TYPE: CHAN 
PROCESS ASSIGNS?: NO 

All of the field prompts and values which are defined within a procedure are stored in a table until 
the procedure terminates. Therefore, when a procedure calls another procedure (or itself), all of 
the field prompts and values for both procedures are stored in the table. As a result of deep level 
nesting, the table can become full and cause the command procedure to abort with the following 
message: 

U SCI-0036 FIELD PROMPT TABLE OVERFLOW 

To prevent table overflow, you should avoid deep levels of nesting and recursive procedures. To 
avoid nesting and still call numerous procedures, call as many procedures as possible at the 
same level. Procedures do not have access to one another’s field prompts. Recursive procedures 
can usually be avoided by using iterative loops within a command procedure. 

3.8.2 Command Processor Design 

A command processor can be written in any language supported by DNOS. The command proces- 
sor is invoked by the command procedure using the .BID or .QBID primitive to Initiate the program 
as a foreground task or a background task, respectively. If the program is run as a foreground 
task, SCI execution is suspended until the task completes. Processors that involve long-term exe- 
cution should operate In background, rather than foreground. 

The following code Is a simple example of a processor written in assembly language invoked by 
the command procedure EXP (defined in the next section): 


EXAMPLE 


IDT EXPRO 

* THIS IS THE E 

* EXP. IT GETS 

* THEM AS A MES 

* MESSAGE IS TH 

* COMMAND INTER 
REF S$GTCA,S$ 
DATA WS,PC,ER 

WS BSS 32 

MSG BYTE 255 

BSS 255 

ERRO BYTE 17 

TEXT ' : END AC 

ERR1 BYTE 27 

TEXT ' : ERROR R 

ERR2 BYTE 27 

TEXT '.-ERROR 

PC BLWP aSSGTCA 

MOV R0,R0 
JNE ERR0R2 
LI R4,MSG 


XAMPLE COMMAND PROCESSOR CALLED BY 
THE 2 PARAMETER VALUES AND RETURNS 
SAGE IN THE MESSAGE BUFFER. THE 
EN DISPLAYED WHEN THE RETURN TO THE 
PRETER IS MADE. 

PARM, S$RTCA, S$STOP 
RORO 

PROCESSOR WORKSPACE 
TOTAL MESSAGE SIZE 
MESSAGE BUFFER 

TION TAKEN' 

ETURNED FROM S$PARM' 

RETURNED FROM S$GTCA' 

GET THE TCA 
TERMINATE 

IF ERROR 
GO GET 
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LI 

R3 , 1 

THE FIRST 



BLWP 

a)S$PARM 

PARAMETER, WHICH 

IS 


BYTE 

R3 , R4 

'•&EXAMPLE NAME" 



MOV 

RO , RO 

TERMINATE 



JNE 

ERR0R1 

IF ERROR 



MOVB 

aMSG, R7 

SET R7 = NUMBER OF 



SRL 

R7,8 

CHARACTERS READ 

IN 


A 

R7,R4 

R4 POINTS TO LAST CHARACTER 

* 



OF FIRST STRING 



NEG 

R7 

R7 = LENGTH OF 



AI 

R7,255 

REMAINING BUFFER 



MOVB 

*R4, R6 

R6 = LAST CHARACTER OF 1ST STRING 


SWPB 

R7 

R4 NOW POINTS TO THE 



MOVB 

R7 , *R4 

REMAINING BUFFER 



LI 

R3,2 

GO GET THE SECOND 



BLWP 

aSSPARM 

PARAMETER , WHICH 

IS 


BYTE 

R3 , R4 

"&NUMBER" 



MOV 

RO, RO 

TERMINATE 



JNE 

ERR0R1 

IF ERROR 



AB 

*R4,aMSG 

aMSG CONTAINS LENGTH 

OF MESSAGE 


MOVB 

R6,*R4 

RESTORE LAST CHAR OF 

1ST STRING 

•k 

NORMAL 

NO ERROR RETURN 



LI 

R2,MSG 

RETURN MESSAGE 



CLR 

R1 



RETURN 

BLWP 

aS$RTCA 

RELEASE TCA 



BLWP 

aS$ST0P 

RETURN TO SCI 


* 

END ACTION 



ERRORO 

LI 

R2, ERRO 




LI 

R1 ,>8000 




JMP 

RETURN 



* 

ERROR RETURN FROM 

S$PARM 


ERR0R1 

LI 

R2, ERR1 




LI 

R1 ,>8000 




JMP 

RETURN 



★ 

ERROR RETURN FROM 

S$GTCA 


ERR0R2 

LI 

R2, ERR2 




LI 

R1 ,>8000 




JMP 

RETURN 




END 





Note that the processor receives its parameters and returns control to SCI by calling various inter- 
face routines (S$GTCA, S$RTCA, S$STOP, S$PARM). These routines are discussed later in this 
section. 

The command processor terminates by calling S$STOP and control returns to the command pro- 
cedure statement following the .BID primitive which invoked the processor. 
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3.8.3 Installing Command Procedures and Command Processors 

After the command procedure and command processor (if applicable) are created, install each of 
them before using the new command. Install the command procedure in a procedure library. 
Although you can install user-defined commands in the .S$CMDS command procedure library, it is 
recommended that you install them in a separate user library to prevent accidental alterations of 
supplied commands. Install the command processors, if used, in a program file. 

You can install command procedures interactively or through batch execution. The foilowing 
example creates a user command procedure library on the system disk and instalis the EXP com- 
mand in that iibrary interactively: 

[3CFDIR PATHNAME=SYSVOL.USERLIB,MAXENT=101 

C3.USE SYSVOL.USERLIB, .S$CMDS 

[l.PROC EXPCEXAMPLE PROCEDURE), 

EXAMPLE NAME=STRIN6(”SAMPLE") , 

NUMBER=INT 

.BID TASK = >5 5,PARMS=("&EXAMPLE NAME" , "&NUMBER") , 

PROGRAM FI LE=.USERPR06 

. EOP 

[] 

The Create Directory File (CFDIR) command creates the user library which is then specified in the 
.USE primitive. By specifying .S$CMDS as the secondary iibrary in the .USE primitive, the standard 
SCI commands are still available to use. Enter the command procedure statements following the 
.USE primitive, if several procedures are to be entered in the same iibrary, additional .USE primi- 
tives are not necessary. 

A batch stream is more efficient than interactive entry, particularly when defining several proce- 
dures. The sequence to create a batch stream for the above command procedure is as follows: 

1. Issue the Execute Text Editor (XE) command without specifying an input FILE ACCESS 
NAME. 

2. Edit the above SCi statements into the file. Include the BATCH and EBATCH commands 
as the first and last commands, respectively. 

3. Issue the Quit Edit (QE) command, do not abort the edit, and specify some file (for 
example, MKC.NEWPROC) as the OUTPUT FILE ACCESS NAME. 

Refer to the DNOS Text Editor Reference Manual for information about the Text Editor. 

Instaii the command procedure by Issuing the Execute Batch (XB) command, specifying 
MKC.NEWPROC as the INPUT ACCESS NAME. When the batch stream completes, check the list- 
ing file for errors. If no errors occurred, the command procedure is instalied in the library 
SYSVOL.USERL1B. 
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The task called by the .BID primitive is the assembly code example used in the paragraphs dis- 
cussing the command processor. Before instailing the command processor, you must compiie or 
assemble the processor and any routines it calls (excluding the S$ routines, which exist in object 
form), then link edit the processor. If the processor uses the S$ interface routines, the link edit 
control file must use the library .SCi990.S$OBJECT containing the S$ routines. Foilowing is an 
example of the Link Editor controi stream needed to link the exampie processor with the interface 
routines: 

LIBRARY .SCI990.S$OBJECT 
PHASE 0, MYPROC1 
INCLUDE .MYPROC1 
END 

After you link edit the processor, install it in a program file using the Instail Task (IT) command. 

3.8.4 Using New Commands 

After you install the command procedures in the .S$CMDS iibrary and the command processors in 
program files, you can issue new commands whenever SCI prompts for a command. If you install 
the new commands in a user command iibrary, you must specify that iibrary by executing the .USE 
primitive before the commands are available. 

The following example specifies a command library, other than .S$CMDS, to be used by SCI: 

[] .USE SYSVOL.USERLIB 
[ ] EXP 

EXAMPLE PROCEDURE 


S$ routines 

Name of linked object module 
Processor object module 


The last .USE primitive executed specifies the current library. Executing the .USE primitive with- 
out a pathname defaults to the system library, .S$CMDS. 

3.8.5 Expert Mode Considerations 

The way SCI commands are entered interactively In expert mode is similar to the way these com- 
mands are entered in batch mode. Enter the command and answer the following prompts and res- 
ponses necessary for command execution. The following is an example of the Show File (SF) 
command: 

SF F=DS02 . USER . TEMP 

After you press the RETURN or ENTER key, the file that you specified is displayed. 

f a command requires additional prompt responses, separate them by commas. If you execute a 
jommand using this method and exclude a prompt necessary for command execution, SCI allows 
^ou to enter a response to that prompt. For instance, suppose SOURCE FILE, DESTINATION FILE, 
ind LISTING FILE were the prompts for a command. Responses to the SOURCE FILE and DESTIN- 
ATION FILE prompts must be supplied, but response to the LISTING FILE is optional. If you enter 
i response to only the SOURCE FILE prompt: 

EX S=DS02. USER. SOURCE 
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then SCI displays the prompts of the command as if you had only entered the command name. 
The cursor is positioned at the prompt which needs a response, as in the foiiowing: 

SOURCE FILE: DS02 . USER . SOURCE 

DESTINATION FILE: (cursor positioned here) 

LISTING FILE: 

This enabies you to enter the response to the DESTiNATION FILE prompt. If necessary, you can 
change the response to the SOURCE FILE at this point. However, SCI will not allow you to enter a 
response to the LISTING FILE prompt; you can only modify responses preceding the cursor posi- 
tion. Press the RETURN key and the command wili execute. 

If a response requires a list of values, this list must be enclosed in parentheses if you are using 
expert mode. 

When you issue a command procedure interactiveiy to caii another command procedure and it 
does not specify any fieid prompts or values for the second procedure, the field prompts for the 
second procedure are displayed. However, If you enter a command procedure in expert mode to 
call another command procedure, the prompts are not displayed for the second procedure. 

Another type of expert mode is used when the the initial or default value is to be used. Enter the 
command with a period as in the following: 

SF . 

Press the RETURN or ENTER key so the file specified as the initial or default value will be dis- 
played. You cannot use this type of expert mode unless the nonoptional command prompts have 
predefined initial or default values. For example, the SF command does not have a default value 
and the Initial value is not assigned until after the first execution of the command. Therefore, if SF 
has not been executed previously, the SF. command would not show a file. 

3.8.6 Deleting Commands 

If you want to delete a command, delete the command procedure from the command procedure 
library and the command processor (if applicable) from the program file in which they are 
installed. Before deleting the command processor, ensure that it is not called by other command 
procedures. 

Delete a command procedure by entering a Delete File (DF) command. The following example 
deletes the EXP command installed In a user library: 

DF PATHNAME=SYSVOL.MYLIB.EXP 

Delete a command processor by using the Delete Task (DT) command. 
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3.9 COMMAND PROCESSOR INTERFACE ROUTINES 

A processor communicates with SCI through command processor interface routines (S$ routines). 
For example, a processor uses the S$PARM routine to obtain the parameters supplied with the 
.BID, .DBID, or .QBID primitives. Calling S$ routines allows you to write processors similar to 
those supplied with DNOS, which contain calls to S$ routines that are transparent to the user. 
Since S$ routines require an assembly language interface, high-level language users must provide 
assembly language routines to call them. Refer to the appropriate language manual for details on 
interface routines. 

Several other DNOS processors provide interfaces similar to the SCI interfaces. These include an 
interface to the mailbox message subsystem and one to the operator interface subsystem. Rou- 
tines with names beginning with MB$ are interfaces to the mailbox message subsystem, and 
those beginning with 01$ are interfaces to the system operator subsystem. The library with the S$ 
routines includes these interface routines. 

3.9.1 Interface Routine References 

References to interface routines in a command processor are external references. Each refer- 
enced routine must be listed in a REF assembler directive in the command processor program. 
Branch and Link Workspace Pointer (BLWP) instructions call interface routines. Sometimes, data 
follows a routine, as specified in the calling sequences of the routine. The following example 
shows the REF directive and the BLWP instructions required in a command processor that calls 
the following interface routines; Get TCA (S$GTCA), Terminate and Return to SCI (S$TERM), and 
Release TCA (S$RTCA). 


REF 


BLWP 


BLWP 


BLWP 


SSGTCA, SSRTCA, SSTERM 


aSSGTCA 


aSSRTCA 


aSSTERM 


Any task using S$ routines must be linked with the routines. They are located in library .SCI990, 
which must be specified for link editing. Tasks written for DX10 must be relinked with DNOS S$ 
routines to execute on DNOS. 

If the S$ routine library for DX10 has been linked with a DNOS task, the following error message 
appears when the task executes: 

★★★ERROR*** TASK ID >xx HAS BEEN LINKED TO DX10 SSROUTINES 
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Where: 

XX is the installed ID of the task. 

This message appears when the S$GTCA routine or the Initialize System Data Base (S$NEW) 
routine executes. 

3.9.2 Buffers for Interface Routines 

Many of the S$ interface routines require buffers. The form of these buffers is as follows: 

LABEL BYTE CNT 

BSS CNT 

CNT represents the number of bytes in the buffer, excluding the count byte. When the buffer con- 
tains a character string, the form is as foliows: 

LABEL BYTE CNT 

TEXT ’ ’. 

CNT EQU $- LABEL- 1 

In this example, symbol CNT represents the number of characters in the string provided by the 
TEXT directive. 

The resulting buffer has the foliowing form: 


STRING 

Cl 

C2 

LENGTH 






BYTE BYTE 




Cn 


2279419 


where: 

string length indicates the number of characters in the string. 

buffer size represents one byte for each character in the string plus one byte reserved for the 
length count. 

Unless otherwise Indicated, all references to buffers in the descriptions of the interface routines 
refer to a buffer with the byte count in the first byte, as in the preceding examples. 

If you create a buffer of length n and you designate the buffer in a routine that returns a value, the 
length byte will receive the length of the returned string. 
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3.10 INTERFACE ROUTINE DESCRIPTIONS 

The six major classes of interface routines are as follows: 

• SCI Interface routines 

• Local display file routines 

• String utility routines 

• Arithmetic utility routines 

• Mailbox message routines 

• Operator interface routines 

3.10.1 SCI Interface Routines 

The SCI Interface routines access parameters (FARMS and CODE), locate and modify synonyms 
defined for the session, and return control to SCI. Only tasks bid with the .BID, .QBID, or .DBID 
primitives can use these routines. The communications area (TCA) serves as an information buffer 
between SCI and the command processors. A call to the S$GTCA routine must precede any calls 
to these S$ routines. After a call to the S$RTCA routine, a call to any of these routines is not valid. 
You can call the S$TERM routine and the Alternate Termination (S$STOP) routine any time, since 
they call S$GTCA. 

3.10.1.1 Get TCA (S$GTCA). Routine S$GTCA makes information available to a command pro- 
cessor. You must call this routine before a command processor can access synonym values or get 
parameters passed to it by the SCI procedure. After a successful call to S$GTCA, the processor 
can retrieve the values of CODE and FARMS. 

Calling Sequence 

BLWP aS$GTCA 

Registers Used 

RO — Error code returned by S$GTCA 
Error Codes 

> FF05 — Unable to access name correspondence table (NCT) 

3.10.1.2 Initialize System Data Base (S$NEW). S$NEW initializes a data base for use by the var- 
ious system routines according to the terminal state, mode, and ID. Some command processors 
do not call S$GTCA because they do not need to access the TCA; however, these processors must 
call S$NEW before they can use any other S$ routines. Processors that call S$GTCA need not call 
S$NEW. 
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Calling Sequence 

BLWP aS$$NEW 
Registers Used 

RO — Error code returned by S$NEW 
Error Codes 

> FFFF — S$NEW previously called 

3.10.1.3 Bid Task Routine (S$BiDT). S$BIDT allows tasks that are normally bid via the .BID or 
.QBID primitives to be bid from another task. S$BIDT aliows a task to repiicate the SCI environ- 
ment at the time a .BID is performed. This capabiilty is also available in COBOL through C$BID 
(which in turn uses S$BIDT) and is avaiiable to other ianguages through an interface to an 
assembly language routine. 

By using S$BIDT, a task can execute other user-written tasks or a system task directiy, without 
returning to SCI to have the .BID primitive execute the task. This allows the task to retain control 
and avoids the problem of having to reenter the task again to resume processing upon return from 
SCI. 

Since S$BIDT can bid any task that the .BID or .QBID primitives can bid, the routine can invoke 
tasks that are part of the operating system release as well as user-written tasks. For example, you 
have an application task that prompts the user for a directory pathname. You could use the 
S$BIDT routine to cali the List Directory task in order to produce an alphabetized listing of the 
members in the directory. The appiication program couid then read this alphabetized iisting and 
prompt the user for desired actions on selected members. After interfacing with the user, the 
application task couid use S$BIDT to cail the Copy Directory task to copy specified members to 
another directory. 

Use of the S$BiDT routine does, however, have severai drawbacks: 

• To call a task directly with S$BIDT routine means bypassing the command procedure. 
Therefore, you risk the fact that a call to a released operating system task may not work 
on a iater release of the operating system due to a change in the .BID calling sequence. 

• The task using S$BIDT must be invoked via a .BID, .QBID, or .DBID primitive. However, a 
task bid via S$BIDT can issue an S$BIDT caii to enabie concatenation. If the task using 
S$BIDT is invoked via XT (Execute Task) or XTS (Execute Task and Suspend SCI), the 
results can be unpredicatable. 

• If the task calling S$BIDT has opened the terminal local file (TLF), the task bid by the 
S$BIDT routine wiil be unable to get access to the TLF and may terminate without per- 
forming the desired action. You can get around this problem, however, by having one of 
the tasks use an aiternate pathname. You can either use DUMY or define your own path- 
name. 
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• If the S$BIDT routine encounters errors when bidding the task, it returns error code. 
However, any error code returned by a task that is called via the S$BIDT routine is very 
difficult to access. If one of your application progranns absolutely needs to access this 
error code, contact your Customer Representative for information. 

As with all S$ routines, a task must call either S$GTCA or S$NEW (to perform the necessary initial- 
izations) before It calls S$BIDT. 

Calling Sequence 

BLWP aS$BIDT 

Registers Used 

RO — Set to 0 by S$BIDT if the task was bid successfully. Set to a nonzero error code by 
S$BIDT if the task was not bid successfully. 

R 1 _ The calling task sets the MSB to the task ID of the task to be executed and the LSB to 
the LUNO assigned to the program file of the task to be executed. 

R2 — Set by the calling task to contain the address of an address table. Each of the 
addresses in the table points to a parameter that will be passed to the task to be exe- 
cuted. This address table must contain a 0 as its last entry. If R2 itself is 0, the parame- 
ters of the calling task are passed to the task to be executed. 

R3 — The calling task sets the MSB to the CODE to be passed to the task to be executed. The 
MSB has an integer range between 0 and 255. It is 0 if no CODE is to be passed; all 
other values correspond to the CODE keyword which may optionally appear on the .BID 
statement. The calling task uses the LSB to set flag bits: 

Bit 8 — If set to 1, the run ID of the bid task is returned in the MSB of R1. If set to 0, R1 
remains unchanged. 

Bit 9 — If set to 0, the calling task is associated with the same station as the caller. If 
set to 1 , the task is not associated with a station. 

Bit 10 — If set to 1, the task shares the synonym table with the caller. If set to 0, the 
called task gets a snapshot of the current synonyms in a table of its own. 

Bit 11 — Set to 0. 

Bit 12 — If set to 1, the calling task is terminated after the called task is bid. 

Bit 13 — Set toO. 

Bit 14 — Set to 0. 

Bit 15 — If set to 1, the calling task is suspended until the called task is terminated. 

If neither bit 12 or bit 15 of R3 is set to 1, the called task and the calling task will run 

concurrently. Therefore, you must not expect the function of the called task to finish 

at any particular time. 
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Error Codes 

> FFFD — S$BIDT is unable to make a snapshot of the current synonyms. 

> FFFE — S$B1DT is unable to bid the task specified. 

S$BIDT can return any error returned by an S$ routine. You can refer to the SCI section of the 

DNOS Messages and Codes Manual for help. 

To illustrate the use of the S$BIDT routine, the following example shows you how to have S$BIDT 
call the Copy/Concatenate (CC) processor: 

1. Examine the command procedure to determine the input values needed for the S$BIDT 
routine. 

CC (COPY/CONCATENATE) , 

INPUT ACCESS NAME(S) = ( ACNM) ("a$SF$P") , 

OUTPUT ACCESS NAME =ACNM 

REPLACE? =ELEMENT(Y=YES,N=NO)(NO), 

MAXIMUM RECORD LENGTH =*INT 
.SYN $SF$P="&INPUT ACCESS NAME" 

★BID TASK CCAF 

.BID TASK=011, UTILITY, C0DE=1 , 

PARMS=( (&INPUT ACCESS N AME ) , "a&OUTPUT ACCESS NAME", 
NO,"&REPLACE",NO,"&MAXIMUM RECORD LENGTH") 

2. Set up the proper data structure to invoke the command procedure. Notice that the CC 
command procedure prompts for responses. It then bids task >11 with a code value of 1 
and passes six parameters. Linder DNOS 1.2, you could invoke the CC procedure with 
the following data structure: 

ADRTBL DATA INPUT 
DATA OUTPUT 
DATA PARM3 
DATA REPLAC 
DATA PARM5 
DATA MAX 
DATA 0 

INPUT BYTE 5 

TEXT (.IN) 

OUTPUT BYTE 4 

TEXT .OUT 
PARM3 BYTE 2 

TEXT NO 
REPLAC BYTE 1 
TEXT Y 
PARM5 BYTE 2 

TEXT NO 
MAX BYTE 0 
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Notice how the parameters being passed match up with the six parameters of the CC 
command procedure. The first parameter passed to the CC procedure is a five-byte 
string “(.IN)”, which represents the input file. The second parameter is a four-byte string 
“.OUT”, which represents the output file. The third parameter is always “NO”. The 
fourth parameter is a one-byte string “Y”, which indicates the output file is to be 
replaced if one already exists. The fifth parameter is always “NO”. The sixth parameter, 
maximum record length, is not being used. Notice also how ADRTBL is terminated by a 
0 and has parameters with the following format: byte 0 is equal to the number of charac- 
ters In the parameter; bytes 1 through N contain the ASCII characters of the parameter. 

3. Set up code to execute the command procedure. Assuming you are using DNOS 1 .2 and 
the calling task is on S$UTIL, you could bid the CC task with the following code: 


LI 

R1 ,>11 FF 

TASK ID 

>11, LUNO FF 

LI 

R2, ADRTBL 

ADDRESS 

OF TABLE 

LI 

R3,>0101 

CODE >01 

, SUSPEND CALLER 

BLWP 

aS$BIDT 

BID CC UTILITY TASK 


This code sets up the registers with the values needed by the CC utility and then passes 
control to the S$BIDT routine. S$BIDT collects the input parameters, performs other 
processing necessary to replicate the SCI environment for the bid, and bids the CC task 
with a copy of the caller’s synonyms and logical names. 

By following the general principles of this example, you can use the S$BIDT routine to execute 
other DNOS or user-written tasks. 

3.10.1.4 Get Parameter (S$PARM). S$PARM returns the parameters in the TCA to the command 
processor. These are the FARMS parameters of the .BID, .QBID, or .DBID primitive. These parame- 
ters are text strings separated by commas. Place an integer indicating the number of the parame- 
ter desired in register Ra. Place the address of a buffer into which the text string is to be copied in 
register Rb. If the buffer is too short, an error code Is returned in register RO. Registers Ra and Rb 
are specified in the two bytes Immediately following the call to S$PARM. 

Calling Sequence 

BLWP aS$PARM 

BYTE Ra,Rb 

Registers Used 

RO — Error code returned by S$PARM 
Ra — Index of desired parameter 

Rb — Address of a buffer in which to place the parameter text string 
Error Codes 

> 901 B — Output buffer too small 

> FF05 — Unable to access NCT 
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Example 

This example retrieves the second parameter text string. The .BID primitive for task EXAM is as 
follows: 

.BID TASK = EXAM, CODE = 37, PROG = VO L . TEST . PROG , 

PARMS = ("&NAME", "aOLDVAL")) 

The command processor accesses the parameter as follows: 

BUF BYTE 20 
BSS 20 
EVEN 

REF SSGTCA, S$PARM, S$RTCA, S$TERM 


ERROR 


BLWP 

aSSGTCA 

GET TCA 

MOV 

R0,R0 

CHECK FOR ERRORS 

JNE 

ERROR 


LI 

R4,2 

ESTABLISH PARAM INDEX 

LI 

R5 , BUF 

ESTABLISH BUFFER POINTER 

BLWP 

aS$PARM 

GET 2ND PARM 

BYTE 

R4, R5 

SSPARM INFO 

MOV 

RO , RO 

CHECK FOR ERRORS 

JNE 

ERROR 


BLWP 

aSSRTCA 

RELEASE TCA 

MOV 

R0,R0 

CHECK FOR ERRORS 

JNE 

ERROR 


LI 

R1 ,>C000 

CONDITION CODE=COOO 

CLR 

R2 

NO VARIABLE TEXT 

LI 

R3,2 

SCI ERROR 

MOV 

RO , R4 

MESSAGE NUMBER 

BLWP 

aS$TERM 

TERMINATE TASK 


2270510-9701 


3-63 



Extending SCI 


3.10.1.5 Get Terminal Status (S$STAT). S$STAT returns the status of the terminal from which 
the command processor was activated. The information is returned as a 32-bit integer. The first 
byte contains the following: 

Bit Contents 

/ 

0 Reserved 

1-3 User privilege code. The hexadecimal values and privilege 

levels are as follows: 

0 Lowest level of access 

1 User defined 

2 System access level 

3 User defined 

4 Management access level 

5 User defined 

6 System and management access level 

7 User defined 

4-7 Current terminal mode, in the form of a hexadecimal number: 

0 Batch mode or background 

1 TTY mode 

F VDT mode 

The second byte contains the station ID, the third byte is reserved, and the fourth byte contains 
the CODE value of the most recent .BID, .DBID, or .QBID. 

Calling Sequence 

BLWP aSSSTAT 

Registers Used 

RO — Error code returned by S$STAT 
R3 — Address of 32-bit buffer 

Error Codes 

None (currently) 

You can issue a call to S$STAT prior to a call to S$GTCA; also, you can issue a call to it after call- 
ing S$RTCA if you call S$NEW first. 

3.10.1.6 Set Synonym Value (S$SETS). The S$SETS routine defines or redefines a synonym in 
the NCT. Place the synonym in a text string buffer at the address in register Ra. Place the value to 
be assigned the synonym in a buffer at the address in register Rb. If register Rb contains 0 or the 
address of a zero-length string, the synonym is deleted from the TCA. 
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Calling Sequence 

BLWP aSSSETS 
BYTE Ra,Rb 

Registers Used 

RO — Error code returned by S$SETS 
Ra — Address of synonym name text string 
Rb — Address of synonym value text string 

Error Codes 


> FF05 — Unable to access NCT 

> FF06 — Synonym table overflow 


Example 


SYNAME 

VALUE 


BYTE 

5 

TEXT 

' SYN01 ' 

BYTE 

14 

TEXT 

' DS02 . LIB . INPUT 

LI 

R3 , SYNAME 

LI 

R4, VALUE 

BLWP 

aSSSETS 

BYTE 

R3 , R4 

MOV 

R0,R0 

JNE 

ERROR 


3.10.1.7 Get Synonym Value (S$MAPS). S$MAPS searches the NCT for the synonym name in a 
buffer at the address in register Ra. With this routine, you can access only synonyms defined by 
S$SETS or by the .SYN primitive. When the synonym is found and the output buffer is large 
enough, the value is placed in the buffer at the address in register Rb. If the buffer is too small, an 
error code is returned in register RO. If the synonym is not found in the TCA, a zero-length string is 
copied into the buffer. When the synonym name contains a period (.), the text preceding the period 
is replaced by its synonym value, if one exists. 

Calling Sequence 

BLWP aSSMAPS 
BYTE Ra,Rb 
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Registers Used 

RO — Error code returned by S$MAPS 

Ra — Address of synonym name text string buffer 

Rb — Address of synonym value text string buffer 


Error Codes 


> 901 B — Output buffer too small 

> FF05 — Unable to access NOT 


Example 


SYNAME 

BYTE 

4 


TEXT 

' SYNM ' 

VALUE 

BYTE 

40 


BSS 

40 


LI 

R2, SYNAM 


LI 

R3, VALUE 


BLWP 

aS$MAPS 


BYTE 

R2,R3 


MOV 

RO, RO 


JNE 

ERROR 


3.10.1.8 Search Name Correspondence Table (S$SNCT). S$SNCT searches the NOT for the 
synonym that is right before or after the character string at the address in register Ra. The NOT in 
the TCA contains synonyms. The value in register RO determines whether the search is for the 
predeceding or the succeeding character in the ASCII character sequence. The original string 
need not appear in the table. 


When the desired synonym is found, the synonym is placed in the buffer at the address in register 
Ra. Its value may be placed in the buffer at the address in register Rb. If no synonym is found, a 
null string (length 0) is placed in the buffer at the address in register Ra. When Ra contains the 
address of a zero-length string and RO contains 0, the routine returns the first synonym in ASCII 
code order. When Ra contains the address of a zero-length string and RO contains - 1, the routine 
returns the last synonym in ASCII code order. When register Rb contains 0, no value is returned. 
The synonym is returned in the buffer at the address in register Ra. Use S$SNCT to access syno- 
nyms in ASCII code order. 
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S$SNCT assumes the following: 

• The Ra and Rb buffers are 255 bytes long (if Rb is not 0). 

• The character count value in the first byte of each buffer is a count of the string cur- 
rently in the buffer. Unless Rb is 0, S$SNCT does not check the buffer length before writ- 
ing in the buffer. 

Calling Sequence 

BLWP aS$SNCT 
BYTE Ra,Rb 

Registers Used 

RO — Set to 0 to search for successor and - 1 to search for predecessor 

Ra — Address of buffer containing original string; synonym name is returned here 

Rb — Pointer to the buffer that receives either the value of the synonym found or 0 

Error Codes 

None (currently) 

Example 


SYN 

BYTE 3 

LENGTH OF SYN BUF 

NAME 

TEXT 'SYN' 

BSS 252 


VALUE 

BYTE 255 

BSS 255 

LENGTH OF VALUE BUF 


LI R0,0 

RO — GET SUCCESSOR 


LI R3,SYN 

R3 — NAME OF SYN 


LI R4, VALUE 

R4=VALUE BUFFER 

GETNXT 

BLWP aS$SNCT 

GET NEXT SYN 


BYTE R3,R4 

DEFINE 'A' AND 'B' 


MOVB ★R3,R1 

MOVE R0,R0 IN ERROR 


JEQ OUT 

CHECK FOR END OF NCT 

★PROCESS 

THE SYNONYM 



3.10.1.9 Split List Into Components (S$SPLT). S$SPLT divides a list and returns the first ele- 
ment and the remainder of the list separately. S$SPLT copies the first element (all text that pre- 
cedes the first comma of the list) in the buffer at the address in register R1 into the buffer at the 
address in register R2. The routine also copies the remainder of the list into the buffer at the 
address in register R3. Registers R1 and R3 can contain the same address. 
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Calling Sequence 

BLWP aSSSPLT 
Registers Used 

RO — Error code returned by S$SPLT 
R1 — Address of list text string 
R2 — Address of buffer to receive first element of list 
R3 — Address of buffer to receive remainder of list 

Error Codes 

> 901 B — Output buffer too smail 

> FFFF — Unbaianced parentheses 

Example 

LIST 

•FIRST' BUF 


LIST BYTE 33 LENGTH OF 

TEXT ' (20, LIST ACCESS' 

TEXT 'NAME, OUTPUT FILE)' 

FIRST BYTE 20 LENGTH OF 

BSS 20 


LI R1,LIST R1 — LIST POINTER 

LI R2, FIRST R2 — FIRST POINTER 

MOV R1,R3 R3 REST POINTER =R1 

BLWP aSSSPLT 
MOV R0,R0 
JNE ERROR 

3.10.1.10 Return Time and Date (S$TAD). S$TAD returns the time and date information that 
DNOS maintains. The routine issues an SVC to obtain the date and time block. The date and time 
from the block are formatted and returned to the calling task. For an initialized date, the string has 
the foiiowing form: 

HR:MIN;SEC WEEKDAY, MONTH, DAY, YEAR. 

When the time and date have not been initialized, only the time is returned. The vaiues returned 
represent the eiapsed time since power was applied to the computer. 

Calling Sequence 

BLWP aS$TAD 

Registers Used 

RO — Error code returned by S$TAD 
R1 — Address of buffer for time and date 


3-68 


2270510-9701 



Extending SCI 


Error Codes 

> 901 B — Output buffer too small 
Example 

This example shows a string returned by S$TAD: 

14:48:16 FRIDAY, NOV 07, 1980. 

3.10.1.11 PutTCA(S$PTCA). S$PTCA should be called before the processor terminates or calls 
S$RTCA. This routine is provided for compatibility with other Model 990 Computer operating sys- 
tems and for future DNOS development. 

Calling Sequence 

BLWP asSPTCA 

Registers Used 

RO — Error returned by S$PTCA 
Error Codes 

None (currently) 

3.10.1.12 Release TCA (S$RTCA). index(S$RTCA Routine) S$RTCA releases the TCA. The 
command processor should call it just before terminating. This routine Is provided for compatibil- 
ity with other Model 990 Computer operating systems and for future DNOS development. 

Calling Sequence 

BLWP aS$RTCA 

Registers Used 

RO — Error code returned by S$RTCA 
Error Codes 

None (currently) 

3.10.1.13 Create Message (S$CMSG). S$CMSG writes a message in a buffer using information 
supplied in registers defined in the calling sequence. Use routine S$CMSG to return an error or 
status message when the command processor continues processing after issuing the message. 
Use routine S$TERM to issue an error or status message and terminate the task. 
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Calling Sequence 

BLWP S$CMSG 
Registers Used 

RO — Error code returned by S$CMSG. 

R1 — Address of the buffer in which the message is returned. The address must be a word- 
aligned (even) address. (The first full word contains the buffer length in bytes.) 

R2 — Address of buffer that contains the variable text. 

R3 — Error source information. 

R4 — Internal message code. 

R 5 _ Address of buffer that contains either the final component of the message file path- 
name orO. 

R6 — Address of buffer that contains additional variable text; applies only when bit 4 of error 
source information word is set to 1. 

R7 — Extra flags word, if R3 so indicates. 

Error Codes 

> 901 B — Output buffer is too small 

Calling this routine requires some analysis of the error condition prior to the call, specifically the 
following: 

• For an SVC error, execute a Return Code Processing SVC (opcode >4C) to obtain the 
message number and other required data. 

• Obtain the file name component of the message file pathname by accessing the value 
of a synonym. You can also obtain the file name if the message file is a system message 
file with a known file name or if the message file is specified with a file indicator. 

Register R1 contains the address of a buffer into which the routine places the message. A mes- 
sage can be more than 255 characters long; the first word of the buffer contains the length of the 
text portion (the remainder) of the buffer. The address must be a word-aligned address. The buffer 
must allow enough space for the message from the file and any anticipated variable text. 

Set register R2 to one of the following; 

• The address of a buffer that contains the variable text for the message 

• The address of a zero-length buffer when no variable text is required 

• Zero 

The count includes the semicolons (;) that separate the variable text elements. A message can 
contain as many as nine variable text elements. You must place data in the buffer that corre- 
sponds to the variable text elements defined for the message. 
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Register R3 contains error source information consisting of four hexadecimal digits. In most 
cases, register R3 is set to 0, indicating that all error source information comes from the file. To 
override the file information, set the leftmost hexadecimal digit to specify the error source as 
follows: 


Value 


Meaning 


0 

1 

2 

4 

6 

8 

A 

C 

E 

F 


Use source information in error file 

Warning 

User error 

System error 

User or system error 

Hardware error 

User or hardware error 

System or hardware error 

User, system, or hardware error 

informative message 


Set the second digit to 0 when no additional variable text is required; set it to 8 to place additional 
text at the end of the message. When you set this digit to 8, you should place the address of the 
buffer that contains this text in register R6. To suppress header information, add 1 to the second 
digit (making it 9 or 1). Set register R7 to >8000 to Indicate header suppression. A 1 in the second 
digit of R3 indicates that register R7 is an additional flags word. 

Set the third and fourth digits to the file Indicator of the message file, as follows: 

Setting Meaning 

> 00 No message file or file identified in register R5 

>01 SVC error message file 

>02 Utility error message file 

> xy Last component of the pathname to which synonym $$$$FNxy 

is assigned ( where xy is greater than or equal to > 80) 

Set register R4 to the internal message code of the desired message. 

Set register R5 to the address of a buffer that contains the file name (last) component of the file 
pathname of the message file that contains the message or that is set to 0. The first byte of the 
buffer must contain the number of bytes of the file name component. This register should be set 
to 0 if the file Indicator in R3 identifies the message file or if no message file is specified. When 
the file indicator is 0 and register R5 contains either 0 or the address of a null string, an abbrevi- 
ated message is written. The abbreviated message consists of the file indicator, message num- 
ber, and variable text. 

Set register R6 to the address of a buffer that contains additional variable text. Set it to 0 when no 
additional text is required. When the second digit of the value in R3 is not set to 8, register R6 does 
not apply. Additional variable text is placed at the end of the specified message independently of 
any question marks in the file message. 

If bit 7 of register R3 equals 1 , register R7 is used as an additional flags word. If bit 0 of register R7 
equals 1, message headers are suppressed. 
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Section 9 provides further information on message file format. 

3.10.1.14 Terminate and Return to SCI (S$TERM). S$TERM sets the termination synonyms and 
terminates the calling task. The following are the termination synonyms: 


Synonym 


Meaning 


$$CC 

$$VT 

$$ES 

$$MN 

$$FN 


Condition code 
Variable text 
Error source 
Internal message code 
Message file name 


Calling Sequence 

BLWP aS$TERM 

Registers Used 

R1 — Value for condition code $$CC 
R2 — Address of buffer that contains variable text 
R3 — Error source information 
R4 — One of the following: 

0 (normal termination) 

Internal message number (non-SVC-detected error) 

Address of SVC block (SVC-detected error to report) 

SCI uses the values of the termination synonyms to provide a warning or error message. When you 
call routine S$TERM at successful termination of a command processor, set registers R1 through 
R4 to 0 to terminate without issuing a message. 

The condition code synonym contains the severity code. Set register R1 to one of the following 
values: 


Value Meaning 

> 4000 Terminated with a warning message 

> 8000 Terminated with an error message for a recoverable error 

>C000 Terminated with an error message for a fatal (unrecoverable 

error 

Set register R2 to the address of a buffer that contains the variable text for the message. Set it to 0 
when no variable text is required. The count of characters in the buffer Includes the semicolons (;) 
that separate the variable text elements. A message can contain as many as 9 variable text ele- 
ments but no more than 235 characters of text. Data must be placed in the buffer that corresponds 
to the variable text elements defined for the message. 
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Register R3 contains error source information consisting of four hexadecimal digits. In most 
cases, register R3 is set to 0, indicating that ail error source information comes from the file. If you 
need to override the file information, set the most significant digit to specify the error source as 
foliows: 


Value 


Meaning 


0 

1 

2 

4 

6 

8 

A 

C 

E 

F 


Use source information in error file 

Warning 

User error 

System error 

User or system error 

Hardware error 

User or hardware error 

System or hardware error 

User, system, or hardware error 

Informative message 


Set the second digit to 0. Set the third and fourth digits to the file indicator of the message file, as 
follows: 


Setting Meaning 

> 00 No message file 

> 01 SVC error message file 

>02 Utility error message file 

>xy Last component of the pathame to which synonym $$FNxy is 

assigned 

Set register R4 to the message number unless the file indicator in register R3 is >01 (SVC error). 
For an SVC error, set R4 to the address of the SVC block. 

3.10.1.15 Alternate Termination (S$STOP). S$STOP is included in DNOS to support command 
processors for earlier operating systems. S$STOP terminates a command processor and returns 
control to SCI. Routine S$TERM performs a similar function with the added capabiiity of providing 
error messages in DNOS format. Use S$TERM in any command processors you write. 

3.10.2 Local Display File Routines 

The TLF is a file of ASCII data to be displayed. Use the TLF for short messages and listings. SCI 
provides a TLF for foreground, background, and batch job modes. SCi displays the contents of the 
foreground TLF immediately prior to displaying the command prompt. The contents of the back- 
ground TLF appear on the screen when you enter either a WAIT or a Show Background Status 
(SBS) command. SCI copies the batch mode TLF into the batch listing file. After displaying the 
TLF, SCI deletes each message. 

The routines described in the following paragraphs open fiies, close files, and build and write 
records to the fiie. The maximum length of a TLF record is 134 characters. Data items are written 
at specific columns, and each line is terminated by a call to S$WEOL. When the text is directed to 
a device instead of to a fiie, these routines add the required device control characters to the text. 
Only tasks executed by means of the .BID, .QBID, or .DBID primitives can successfully call these 
routines. 


2270510-9701 


3-73 



Extending SCI 


3.10.2.1 Open File (S$OPEN). S$OPEN opens the TLF or a user-specified file for write access. 
If register R1 contains 0, S$OPEN opens the TLF. 

Calling Sequence 

BLWP aS$0PEN 

Registers Used 

RO — Error code returned by S$OPEN 

R1 — 0 or the address of the buffer that contains the pathname of the device to call or file to 
open 

Error Codes 

>A1xx — Assign or open error, I/O error code xx 
>9022 —Invalid use of device 
>9026 —Invalid file type 

3.10.2.2 Open File Specifying User ID (S$OPNS). S$OPNS opens a specified file in the same 
way S$OPEN does but has one additional feature: when the Assign LUNO is performed on the file, 
a specified user ID and passcode are used for security purposes. However, if the calling task is a 
security bypass task, the passcode field is ignored. 

If register R1 contains 0, S$OPNS opens the TLF. 

Calling Sequence 

BLWP a)S$0PNS 

Registers Used 

RO — Error code returned by S$OPNS. 

R1 — 0 or the address of the buffer that contains the pathname of the device or file to open 
R2 — Address of a buffer with the user ID parameters. The buffer begins with two bytes val- 
ues. The first byte has a value of >02; the second a value of > 10. These bytes are then 
followed by two eight-character fields. The first contains the user ID; the second the 
password. Each of these two fields should be right filled with blanks if the values are 
less than eight characters long. 

Error Codes 

>A1xx — Assign or open error, I/O error code xx 
> 9022 — Invalid use of device 
>9026 —Invalid file type 
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3.10.2.3 Write to File (S$WRIT). S$WRIT concatenates the text string addressed by register R1 
with the current line to be written to the file. When register R2 contains 0 or a positive value, the 
value specifies the column (0 through 133) in which the text begins. A negative value in R2 is not 
valid. When any byte in the string contains >7F, the immediately preceding character is repeated. 
The byte following the byte that contains >7F specifies the number of repetitions. The string 
should not contain device control characters, such as a line feed; S$WRIT supplies these as 
needed. 

Calling Sequence 

BLUP aSSWRlT 
Registers Used 

RO — Error code returned by S$WRIT 
R1 — Address of text to be written 
R2 — Starting column in the record 

Error Codes 

>FFF8 — File is not open 

> FFF9 — Start position is too small 

> FFFA — Text buffer overflow 

3.10.2.4 Write End-of-Line to Flle(S$WEOL). S$WEOL terminates the current line to be written 
and writes it to the file. If S$WRIT has not supplied any text since the file was opened or since the 
previous line was written, S$WEOL writes a blank line. 

Calling Sequence 

BLUP aS$WE0L 

Registers Used 

RO — Error code returned by S$WEOL 
Error Codes 

>A1xx — I/O error XX has occurred 
>FFF8 — File is not open 

3.10.2.5 Close File (S$CLOS). S$CLOS terminates writing to the file. You should call S$CLOS if 
the file was opened prior to a call to S$TERM. When register R1 contains 0 and the file is the TLF, 
the TLF appears on the screen after the command completes and before the termination message 
appears. 

When R1 contains a nonzero value, the lines that were written to the TLF since the last call to 
S$OPEN or S$OPNS are erased from the TLF. 
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Calling Sequence 

BLWP aS$CLOS 
Registers Used 

RO — Error code returned by S$CLOS 
R1 — Display flag 


Error Codes 

> FFF8 — TLF is not open 

3.10.2.6 Local Display File Example. The following example includes a call to each of the local 
display file routines: 

Example 


BYTE 

10 


TEXT 

'THIS IS 

A ' 

BYTE 

16 


TEXT 

•TLF TEST 

MESSAGE' 

CLR 

R1 

TLF TO BE OPENED 

BLWP 

aS$0PEN 

OPEN TLF 

MOV 

RO , RO 

TEST FOR ERROR 

JNE 

ERROR 



LI 

R1 ,M1 

MESSAGE ADDRESS 

LI 

R2,0 

COLUMN ADDRESS 

BLWP 

aS$WRIT 

WRITE Ml 

MOV 

RO , RO 

TEST FOR ERROR 

JNE 

ERROR 


LI 

R1 ,M2 

MESSAGE ADDRESS 

LI 

R2,11 

COLUMN ADDRESS 

BLWP 

aSSWRIT 

WRITE M2 

MOV 

RO , RO 

TEST FOR ERROR 

JNE 

ERROR 
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BLWP 

aS$WE0L 

WRITE END-OF-LI 

NE 

MOV 

RO , RO 

TEST FOR ERROR 


JNE 

ERROR 



CLR 

R1 

CLEAR DISPLAY F 

LAG 

BLWP 

aS$CL0S 

CLOSE & DISPLAY 

TLF 

MOV 

RO, RO 

TEST FOR ERROR 


JNE 

ERROR 



LI 

R1 ,>C000 

CONDITION C0DE= 

COOO 

CLR 

R2 

NO VARIABLE TEXT 

LI 

R3,2 

SCI ERROR 


MOV 

RO, R4 

MESSAGE NUMBER 


BLWP 

aSSTERM 

TERMINATE TASK 



3.10.3 String Utility Routines 

The string utility routines copy, compare, and convert character strings. The string buffer required 
by these routines has the form previously described. 

An empty buffer reserved for string storage should indicate the size of the buffer (minus 1) in the 
first byte. 

The string utility routines are as follows: 

• S$INT — Convert ASCII to Binary Integer 

• S$IASC — Convert Binary Integer to ASCII 

• S$SCOM — Compare Strings 

• S$SCPY — Copy String 

3.10.3.1 Convert ASCII to Binary Integer (S$INT). S$INT converts an ASCII text string that repre- 
sents an integer expression into a 32-blt binary value. The Integer expression to be converted can 
contain the standard arithmetic operators -i-, -, *, and /. Register R4 contains the base of the 
numbers to be converted. When the ASCII string contains numbers beginning with > or 0, the 
numbers are converted as hexadecimal numbers regardless of the base specified in register R4. 

Calling Sequence 

BLWP aSSiNT 

Registers Used 

RO — Error code returned by S$INT 

R2 — Address of buffer that contains ASCII code to be converted to binary integer 

R3 — Address of a 32-bit buffer in which the converted value Is stored 

R4 — Base of number represented by the input string; a 0 value indicates base 10 


2270510-9701 


3-77 



Extending SCI 


Error Codes 

>9002 — Invalid integer expression 
> FFFF — Divide by zero 

Example 


BUFF 

BYTE 

LNG 

TEXT STRING TO BE CONVERTED 


TEXT 

•33000' 


LNG 

EQU 

$-BUFF-1 

LENGTH CALCULATION 

NMB 

BSS 

4 

BUFFER FOR BINARY VALUE 


LI 

R2, BUFF 

ADDRESS OF TEXT STRING 


LI 

R3,NMB 

BUFFER ADDRESS FOR BINARY NO 


LI 

R4,0 

SET FOR BASE 10 


BLWP 

aS$INT 

CONVERT TEXT STRING TO BINARY 


MOV 

RO, RO 

PASS ERROR CODE 


JNE 

ERROR 



3.10.3.2 Convert Binary Integer to ASCII (S$IASC). S$IASC converts a 32-bit binary integer into 
an ASCII text string representing that number. The 32-bit integer is converted as a two’s comple- 
ment number or a 32-bit positive binary number, depending on the base specified in register R3. If 
the base is 0, the number is converted as a two’s complement binary integer. It is converted into 
the ASCII representation of the decimai (base 10) number with leading blanks and a minus sign for 
a negative number. If the base does not equal 0, the 32-bit integer is considered to be positive; it Is 
converted into the ASCII representation of the integer in the specified base, with leading zeros. 

Calling Sequence 

BLWP aSSIASC 

Registers Used 

RO — Error code returned by S$IASC. 

R1 — Address of the 32-bit integer. 

R2 — Address of the buffer to receive the ASCII text string. The first byte of the buffer must 
contain the buffer length minus 1. The buffer must be large enough to contain the larg- 
est possible values. 

R3 — In byte 0, number of ASCII characters to be returned; 0 means variable number; 
maximum is 32. 

In byte 1, base (for example, 10 or 16) into which integer is to be converted prior to 
representation in ASCII; 0 means decimal. 
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Error Codes 

>901B — Output buffer is too small 
> FFFF — Field width is greater than 32 

Example 


BUFF 

BYTE 

15 

BUFFER FOR ASCII VALUE 


BSS 

15 


NMB 

DATA 

>20 

NUMBER = >20 


DATA 

0 



LI 

R2 , BUFF 

ADDRESS OF TEXT STRING 


LI 

R1 , NMB 

ADDRESS OF BINARY NUMBER 


LI 

R3 ,0 

VARIABLE LENGTH/BASE 10 


BLWP 

aS$IASC 

CONVERT BINARY TO ASCII 


MOV 

RO , RO 

PASS ERROR CODE 


JNE 

ERROR 



3.10.3.3 Compare Strings (S$SCOM). S$SCOM compares two strings and sets the equal and 
arithmetic greater than bits (bits 1 and 2) of the status register and register RO to the resuits of the 
comparison, if one string is shorter than the other, it is treated as if it is fiiled to the right with null 
characters (>00). If one string is a substring of the other (matching from the left), RO is set to 0. 
The addresses of the two strings are in registers Ra and Rb. Registers Ra and Rb are specified in 
the two bytes immediately following the call. 

Calling Sequence 

BLWP aS$SC0M 
BYTE Ra.Rb 

Registers Used 

RO — Substring test code returned by S$SCOM: 0 = one string is a substring - 1 = strings 
do not match 

Ra — Address of the buffer that contains the first string 
Rb — Address of the buffer that contains the second string 

Error Codes 

Status returned in RO 
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Example 

FIRST 

SECOND 


BYTE 

6 

LENGTH OF FIRST 


TEXT 

' SUBSTR ' 

STRING 


BYTE 

9 

LENGTH OF SECON 

D 

TEXT 

' SUBSTRING ' 

STRING 


LI 

R3 , FIRST 

R3 POINTS TO FI 

RST 

LI 

R5 , SECOND 

R5 POINTS TO SE 

CON 

BLWP 

as$scoM 

COMPARE THE TWO 


BYTE 

R3 , R5 

DEFINE 'A' AND 

•B' 

J EQ 

OUT 

THIS JUMP WILL 

NOT 

MOV 

RO , RO 

OCCUR 


J EQ 

SUB 

THIS JUMP WILL 

OCC 


3.10.3.4 Copy String (S$SCPY). S$SCPY copies the string at the address in register Ra into the 
buffer at the address in register Rb, placing the length of the copy string in the first byte of the 
buffer. Registers Ra and Rb are specified in the two bytes immediately following the call. The 
buffer containing the string to be copied must not overlap the receiving buffer. If the length of the 
receiving buffer is less than the length of the string to be copied, an error code is returned in regis- 
ter RO. When register Ra contains 0 or the address of a null string (zero length), the first byte of the 
buffer at the address in register Rb is set to 0. 


Calling Sequence 


BLWP aS$SCPY 
BYTE Ra,Rb 

Registers Used 

RO — Error code returned by S$SCPY 

Ra — Address of buffer that contains text to be copied 

Rb — Address of buffer to receive copy 


Error Codes 


> 901 B — Output buffer too small 


Example 


STRING 

BYTE 7 
TEXT 

'COPY ME' 

LENGTH OF STRIN 

COPY 

BYTE 

20 

LENGTH OF BUFFE 


BSS 

20 



LI 

R1 , STRING 

R1=P0INTER TO S 


LI 

R8, COPY 

R8=P0INTER TO B 


BLWP 

aS$SCPY 

CALL SSSCOPY 


BYTE 

R1 , R8 

DEFINE 'A' AND 


MOV 

RO, RO 

TEST FOR ERROR 


JNE 

ERROR 



3-80 


2270510-9701 



Extending SCI 


ERROR 


LI 

R1 ,>C000 

C LR 

R2 

LI 

R3,2 

MOV 

RO , R4 

BLWP 

aS$TERM 


CONDITION COD 
NO VARIABLE T 
SCI ERROR 
MESSAGE NUMBE 
TERMINATE TAS 


E = C000 
EXT 

R 

K 


3.10.4 Arithmetic Utility Routines 

The arithmetic utiiity routines perform addition, subtraction, muitipiication, and division with 32- 
bit signed integer operands. The operands must be in binary form. Ail of the routines allow the 
addresses of the operands and the addresses of the results to be the same. The logical greater 
than, arithmetic greater than, and equal bits in the status register (bits 0 through 2) are set or reset 
as assembly language instructions would set them. 

The following routines are available: 

S$IADD — Add 32-bit integers 

S$ISUB — Subtract 32-bit integers 

S$IMUL — Multiply 32-bit integers 

S$IDIV — Divide 32-bit integers 

3.10.4.1 Add 32-Bit Integers (S$IADD). S$IADD adds two 32-bit integers in two’s complement 
form. The sum is a 32-bit two’s complement integer. Registers R1 and R2 contain the addresses of 
the two integers, and the sum is placed in the address in register R3. 

Calling Sequence 

BLWP aS$IADD 

Registers Used 

RO — Error code returned by S$IADD 
R1 — Address of the 32-bit buffer containing the addend 
R2 — Address of the 32-bit buffer containing the addend 
R3 — Address of the 32-bit buffer for the sum 

Error Codes 

> FFFF — Numeric overflow 
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Example 


NUM1 

DATA 

>0000 

BUFFER FOR 

32-BIT INTEGER 


DATA 

>1111 



NUM2 

DATA 

0 

BUFFER FOR 

32-BIT INTEGER 


DATA 

>0145 



RESLT 

BSS 

4 

BUFFER FOR 

32-BIT SUM 


LI 

R1 ,NUM1 

ADDRESS OF 

INTEGER 


LI 

R2,NUM2 

ADDRESS OF 

INTEGER 


LI 

R3 , RESLT 

ADDRESS OF 

RESULT BUFFER 


BLWP 

aS$I ADD 

PERFORM ADDITION 


MOV 

RO, RO 

PASS ERROR 

CODE 


JNE 

ERROR 




3.10.4.2 Subtract 32-Bit Integers (S$ISUB). S$ISUB subtracts 32-bit integers, if register R1 con- 
tains 0, S$iSUB caicuiates the negative of the number at the address in register R2, that is, 0 
minus the number. 

Calling Sequence 

BLWP aS$ISUB 

Registers Used 

RO — Error code returned by S$iSUB 
R1 — Address of the 32-bit buffer containing the minuend 
R2 — Address of the 32-bit buffer containing the subtrahend 
R3 — Address of the 32-bit buffer for the difference 

Error Codes 

> FFFF — Numeric overflow 
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Example 


NUM1 

DATA 

DATA 

>0000 

>1111 

BUFFER 

FOR 

32-BIT 

INTEGER 

NUM2 

DATA 

DATA 

0 

>0145 

BUFFER 

FOR 

32-BIT 

INTEGER 

RESIT 

BSS 

4 

BUFFER 

FOR 

32-BIT 

RESULT 


LI 

R1 , NUM1 

ADDRESS OF 

INTEGER 

LI 

R2, NUM2 

ADDRESS OF 

INTEGER 

LI 

R3 , RESLT 

ADDRESS OF 

RESULT BUFFER 

BLW 

P aSSISUB 



MOV 

RO , RO 

PASS ERROR 

CODE 

JNE 

ERROR 




3.10.4.3 Multiply 32-Bit Integers (S$IMUL). S$IMUL multiplies two 32-bit integers. Registers R1 
and R2 contain the addresses of the integers, and S$IMUL places the 32 least significant bits of 
the product in the buffer at the address in register R3. No overflow indication is returned. 

Calling Sequence 

BLWP aS$IMUL 

Registers Used 

RO — Error code returned by S$IMUL 
R1 — Address of the 32-bit buffer containing the multiplier 
R2 — Address of the 32-bit buffer containing the multiplicand 
R3 — Address of the 32-bit buffer for the product 

Error Codes 

None (currently) 
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Example 


UM1 

DATA >0000 

DATA >1111 

BUFFER 

FOR 

32-BIT INTEGER 

UM2 

DATA 0 

DATA 0145 

BUFFER 

FOR 

32-BIT INTEGER 

ESLT 

BSS 4 

BUFFER 

FOR 

32-BIT INTEGER 


LI R1,NUM1 

ADDRESS 

OF 

INTEGER 


LI R2,NUM2 

ADDRESS 

OF 

INTEGER 


LI R3,RESLT 

ADDRESS 

OF 

RESULT BUFFER 


BLWP aS$IMUL 

MOV R0,R0 

JNE ERROR 

PERFORM 

MU 

LTIPLICATION 


3.10.4.4 Divide 32-Bit integers (S$iDiV)- S$IDIV divides the 32-bit integer at the address in reg- 
ister R1 by the 32-bit integer at the address in register R2. The routine places the quotient in the 32- 
bit buffer at the address in register R3 and the remainder in the 32-bit buffer at the address in 
register R4. When registers R3 and R4 contain the same address, the quotient is stored at the 
address and no remainder is stored. 

Calling Sequence 

BLWP as$iDiv 

Registers Used 

RO — Error code returned by S$IDIV 
R1 — Address of the 32-bit buffer containing the dividend 
R2 — Address of the 32-bit buffer containing the divisor 
R3 — Address of the 32-bit buffer for the quotient 
R4 — Address of the 32-bit buffer for the remainder 

Error Codes 

> FFFF — Divide by zero 
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Example 


NUM1 

DATA >0000 

DATA >1111 

BUFFER FOR 

32-BIT INTEGER 

NUM2 

DATA 0 

DATA >0145 

BUFFER FOR 

32-BIT INTEGER 

QUOT 

BSS 4 

BUFFER FOR 

32-BIT QUOTIENT 

RMDR 

BSS 4 

BUFFER FOR 

32-BIT REMAINDER 


LI R1,NUM1 

ADDRESS OF 

INTEGER 


LI R2,NUM2 

ADDRESS OF 

INTEGER 


LI R3,QU0T 

ADDRESS OF 

QUOTIENT BUFFER 


LI R4,RMDR 

ADDRESS OF 

REMAINDER BUFFER 


BLWP as$iDiv 

PERFORM DIVISION 


MOV R0,R0 

JNE ERROR 

PASS ERROR 

CODE 

3.10.5 Spooler Interface Routine (S$SPLR) 



The S$SPLR routine allows you to access the spooler subsystem from your task environment. This 
routine supports all spooler commands that SCI supports. It can be called only from assembly 
language routines. 

Routine S$SPLR builds a print request message to the spooler subsystem from information you 
provide. 

Calling Sequence 

BLWP as$SPLR 

Registers Used 

RO — Error code (returned) 

R1 — Address of Spooler Control Block (SCB) 

Note that R1 is changed to point to an SVC block if error < 90FF is returned in RO. 
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The SCB template is in the template directory with the other system templates. It contains the fol- 
lowing Information: 


Offset (in Bytes) 

Data Type 

Contents 

0 SCBOP 

Byte 

Spooler message code 

1 SCBFLO 

Boolean 

Flags 

2SCBFLG 

Boolean 

Informative flags 

4SCBSID 

Character 

Spooler ID 

10 SCBDEV 

Character 

Device or class name 

18SCBUSR 

Pointer 

SCI string for user ID 

20 SCBJNM 

Pointer 

SCI string for job name 

22 SCBPTH 

Pointer 

SCI string for file pathname 

24 SCBFRM 

Pointer 

SCI string for requested form 

26 SCBPAG 

Word 

Integer, number of pages on 
resume 

28 SCBCOP 

Byte 

Number of copies 

29 SCBLPP 

Byte 

Lines per page 

30SCBPRI 

Byte 

Job priority 

31 SCBXXX 

Byte 

Reserved 

32 SCBDVP 

Pointer 

SCI string for device or class 
name 


The following values are valid for the SCBOP field: 

Value Meaning 

1 Print file message 

2 Halt output message 

3 Resume output message 

4 Kill output message 

5 Modify output message 

6 Modify Spooler device message 

7 Verify validity of device or class name message 
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The following are SCBFLO field definitions: 


Bit 

Name 

Meaning 

0 

SCFDVP 

T rue; use SCBDVP rather than SCBDEV 

1 through 7 


Each bit is reserved and must be 0 

The following are SCBFLG field definitions: 

Bit 

Name 

Meaning 

0 

SCFUSE 

T rue; delete the spooler device 

1 

SCFAVL 

True; not available to the spooler 

2 

SCFPGD 

True; reverse paging on resume output 

3 

SCFR1 

Reserved; must be 0 

4 

SCFR2 

Reserved; must beO 

5 

SCFANS 

True; ANSI file 

6 

SCFBNR 

T rue; no banner sheet desired 

7 

SCFDAP 

True; delete after printing 

8 

SCFIMM 

True; halt immediately, not at end-of-file (E 

9 

SCFR3 

Reserved; must beO 

10 

SCFR4 

Reserved; must be 0 

11 

SCFR5 

Reserved; must be 0 

12 

SCFSHR 

True; remote/shared device 

13 

SCFDAL 

True; delete always (even if a kill output is 
done later) 

14 


Reserved; must be 0 

15 


Reserved; must be 0 


S$SPLR makes the foiiowing assumptions about the SCB. 

• The device or ciass name entry must be ieft justified and biank fiiied to the right. 

• The SCBUSR, SCBPTH, SCBJNM, and SCBFRM fieids are SCi string pointers. 

• SCBJNM and SCBUSR fieids are bandied in a special manner. S$SPLR uses the job 
name and user ID that the job manager SVC >48 (Get Job Information) biock returns if 
the field Is 0, the length of the string is 0, or the length of the string exceeds eight char- 
acters. Otherwise, S$SPLR uses the user-supplied string. 

• When the SCBOP field specifies a print file message, S$SPLR uses the default form 
name STANDARD if the SCBFRM field is 0, the length of the string is 0, or the length of 
the string exceeds eight characters. 
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• The SCBSID field is returned to you if the print file message is successfully processed. 

• If the SCBCOP field is 0 or greater than 127, a value of 1 is used. 

• You can send messages using the Modify Spooi Device (MSD) command to the spooier, 
but S$SPLR does not change ciass name definitions. Aiso, you cannot specify ciass 
names in defining any new device to the spooier. 

• If you want to use the Modify Output function, a value of > FF in the SCBPRI and 
SCBCPY fields indicates that the previous value does not change. 


Error Codes 


0 

>90FF 

>9110 

>906B 

>910F 

>9112 

>9187 

>9194 

>9195 

>925F 

>9205 

>9207 

>9206 

>9255 

>907D 

>9191 

>9193 

>94FF 


— Successful completion 

— returned in R1 

— Invalid device name or class name 

— Invalid spooler message code (error in S$SPLR) 

— Spooler cannot assign spool ID to requested file 

— Invalid pathname received 

— Access is not appropriate to honor request 

— Device is not available now 

— Device cannot be remote/shared an available to spooler simultaneously 

— Invalid concatenated pathname syntax 

— Number of characters in concatenate pathname set exceeds decimal 256 

— Invalid calling sequence to S$SPLR 

— SCB aligned on an odd-address boundry 

— Invalid spooler ID sent to spooler 

— Invalid priority specified 

— Device is active; request cannot be honored 

— Maximum allowable number of devices has been entered 

— Errors returned by the job manager SVC > 48, and the I/O subsystem for 
assign, open, write, close, and release LUNO SVC requests 


If an error occurred on an open, write, or close of the spooler channel .S$DSTCHN, you must either 
close the LUNO, release the LUNO, or both. Since the DNOS error processor SVC expects the SVC 
block causing the error to be intact, no intermediate operations could have been performed using 
the call block that caused the error. Therefore, S$SPLR cannot close or release the LUNOs, and 
you must perform these operations after calling the return code processor. If you choose to termi- 
nate on the error condition, the operating system closes or releases the LUNOs automatically. 

3.10.6 Operator Interface Routines 

These routines allow user-written tasks to create operator messages and to receive responses 
made by the operator. 


The operator interface routines are as follows: 

• OI$BGN — Initializes operator interface subsystem 

• OI$COM — Creates an operator message 
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• OI$WAT — Causes the task to wait for an operator response 

• OI$END — Terminates the operator interface subsystem session 

3.10.6.1 Initialize Operator Interface (OI$BGN). Routine OI$BGN must be called before the 
operator interface is available for use by the calling task. It assigns a LUNO to the operator inter- 
face IPC channel. 

Calling Sequence 

BLWP aOI$BGN 

3.10.6.2 Create Operator Message (OI$COM). Routine OI$COM initiates an operator message 
and returns immediately to the calling task. 

Calling sequence 

BLWP a0I$C0M 

Registers Used 

R 1 _ MSB: time-out in minutes LSB: number of prompts (0 - 2) 

R2 — Address of buffer containing operator message 
R3 — Address of buffer containing first prompt (if any) 

R4 — Address of buffer containing default response for first prompt (if any) 

R 5 _ Address of buffer containing second prompt (if any) 

R6 — Address of buffer containing default response for second prompt (if any) 


Error Codes 


>90FF 

>9100 

>9101 

>9102 

>9103 

>9104 

>9105 

>9106 

>910C 

>910F 


SVC error 

Number of prompts Is greater than 2 

Address pointer of operator response is 0 

Operator message length is 0 

Address pointer of first prompt and default is 0 

Illegal operator message length 

Address pointer of second prompt and default is 0 

Prompt has Illegal message length 

OI$COM called previously with reply outstanding 

Time delay exceeded 


A 0 time-out value specified in the lower byte of register R1 indicates that no response is required. 
A second prompt cannot be specified unless a first prompt is specified. If prompts are specified, 
default responses are optional. A 0 value, or an address pointing to a null string (length of 0), in 
any of the buffer registers indicates no string. 

If no error is returned, the specified message is sent to the operator interface subsystem as an ini- 
tiated operation. To receive responses from the operator, OI$WAT must be called. 
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3.10.6.3 Wait for Operator Response (OI$WAT). The caller uses OI$WAT to wait for an operator 
response. 

Calling Sequence 

BLWP aOI$WAT 
BYTE Ra,Rb 

Registers Used 

Ra — Address of buffer in which operator response to first prompt is to be placed 
Rb — Address of buffer in which operator response to second prompt is to be piaced 


A zero vaiue in either register indicates no buffer. 


Error Codes 


>90FF 

>9107 

>9108 

>9109 

>910A 

>910B 

>910E 

>9110 


— SVC error 

— Address pointer of message is 0 

— Message buffer is too smaii 

— No message outstanding 

— Negative response by operator 

— Previous message timed out without response 

— Operator interface not initialized 

— Operator interface error returned 


Only one operator message may be outstanding at any given moment. No error is given if a task 
sends a message that compietes, and then sends another message without testing for a response 
to the first message. An operator can cause a negative response to be returned by issuing a KOR 
(Kiil Operator Request) command, if a negative response is returned, Oi$WAT wiil set the status 
register to a not equai status. Otherwise, an equal status is returned. 


3.10.6.4 End Operator Interface Subsystem Interface Session (OI$END). Routine OI$END ter- 
minates communication with the operator interface subsystem and reieases the LUNO to the 
operator channei. 


Calling Sequence 

BLWP a0I$END 


Error Codes 


>90FF — SVC error 


After cailing this routine, the operator interface may no longer be used until a new call to OI$BGN 
is made. Any outstanding operator messages are aborted. 
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3.10.7 Mailbox Subsystem Interface Routines 

The mailbox subsystem interface routines route messages among tasks. The routines are as 
follows: 

• MB$INT — Initializes mailbox interface 

• MB$SND — Allows a task to send mail to an addressee 

• MB$RCV — Allows a task to receive mall 

• MB$RLS — Allows a task to stop receiving mail 

3.10.7.1 Initialize Maiibox interface (MB$iNT). Routine MB$INT must be called before any other 
mailbox interface routines may be called. This routine assigns a LUNO to the mailbox channel and 
initializes the mailbox interface. 

Calling Sequence 

BLWP BMBSINT 

Registers Used 

RO — Error code returned by MB$INT 
R1 — One of the following: 

* Address of SVC call block if an error is returned 
*Points to a site name string on entry 


Error Codes 

>90FF — SVC error 


3.10.7.2 Send Mail (MB$SND). Routine MB$SND allows a task to send mail to an addressee. 
Calling Sequence 

BLWP a)MB$SND 
Registers Used 

R1 — Address of buffer that contains message text 

R2 — Address of buffer that contains name of addressee (one to eight characters) 


Error Codes 


>90FF 

>9100 

>9101 

>9102 

>9103 

>9104 


— SVC error 

— No message buffer specified 

— No addressee buffer specified 

— Message length of 0 specified 

— Illegal addressee buffer length 

— All-blank addressee specified 
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3.10.7.3 Receive Mail (MB$RCV). Routine MB$RCV allows a task to receive mall addressed to 
any one of up to three names. 

Calling Sequence 

BLWP aMB$RCV 


Registers Used 

R1 — Address of buffer that contains message text 
R2 — Address of buffer that contains time and date 
R3 — Name list in the format: 


< length of list> < name length> < name> ... 
Each name can be one to eight characters in length. 


The time and date returned is in ASCII string format. It is same format as SCI displays when a 
Create Message (CM) message is received. It is the time and date when mailbox received the mail, 
not when the mail was requested through MB$RCV. 


Error Codes 


>90FF 

>9105 

>9106 

>9107 

>9108 

>9109 

>910A 

>910B 

>910C 


— SVC error 

— All blank name specified in name list 

— Name length exceeds eight characters 

— Name list length exceeds 28 characters 

— No name list specified 

— Time and date buffer too small 

— Message buffer too small 

— No time and date buffer specified 

— No message buffer specified 


3.10.7.4 Release Mailbox (MB$RLS). Routine MB$RLS allows a task to stop receiving mail from 
the mailbox. This routine can receive any mail that has been received since the last call to 
MB$RCV. 


Calling Sequence 

BLWP a)MB$RLS 
Registers Used 

R1 — Address of buffer that contains message text 
R2 — Address of buffer that contains time and date 

Errors Codes 

>90FF — SVC error 
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4.1 NEED FOR AN SVC PROCESSOR 

About 70 supervisor calls (SVCs) are included with DNOS to perform services and provide access 
to data structures. However, certain situations require additional, special SVCs. DNOS allows you 
to write your own SVC processor and Include it as part of DNOS during system generation. 


4.2 HOW TO WRITE AN SVC PROCESSOR 

To add an SVC to DNOS, you must design the call block for the SVC, build several tables, write a 
processor for the SVC, and include relevant information during system generation. 

4.2.1 SVC Call Block 

Because of the close relationship between the SVC call block and the SVC processor, only the 
writer of the processor can design the call block. Except for the first three bytes, you must deter- 
mine the size and content according to the SVC functions to be performed. 

Byte 0 of the call block must contain the SVC opcode. The standard set of SVCs uses opcodes 
ranging from 0 through > 7F. You can implement SVCs using opcodes from > 80 through > FF. You 
can specify one or more opcodes using any codes within the user-defined range. 

The SVC processor returns a code in byte 1 of the SVC call block. This code is 0 when the SVC 
completes normally. A code other than 0 is returned when an error occurs or a warning is 
appropriate. 

Byte 2 of the call block contains a subopcode when an SVC supports several operations. When an 
SVC performs only one operation, you can use byte 2 for any purpose. 

To allow for adaptations or extensions to an SVC and its processor, you should include a reserved 
word at the end of the defined call block. Also, you should make the block an even number of 
bytes beginning on a word boundary. 

4.2.2 SVC Definition Tabies 

To enable the processor to operate as efficiently as possible, the operating system copies some 
or all of the call block into a special structure for use by the SVC processor. You must specify how 
much information to copy and how much to return to the user task in a pair of tables defined for 
each SVC. These tables are included in a module of definition information for use by system gen- 
eration. The module can be built in any file but must include the following: 

• The IDT name, RPUDAT 

• DEF statements for RPUMAX and RPUTAB 
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• A REF statement for each SVC processor entry point 

• A byte named RPUMAX that contains the largest user-defined SVC opcode 

• A table named RPUTAB that contains a two-word entry for each SVC opcode in the 
range > 80 through RPUMAX 

• A request description block (RDB) for each user-defined SVC 

• A return information block (RIB) for each user-defined SVC that returns data to the 
calling task 

The entries in the table RPUTAB consist of two words each. The first word contains > EOOO, and 
the second contains the address of the RDB for the SVC opcode being defined. The first entry in 
the table is for SVC opcode > 80. Each successive entry is for the next SVC opcode in sequence. If 
a particular opcode is not defined in the system being generated, the entry in RPUTAB must con- 
sist of two words of zero. The RPUDAT module must be assembled, and the object module path- 
name of the module must be supplied to the system generation program. Figure 4-1 shows an 
example of RPUTAB that lists two SVCs defined by the user. 

An RDB includes the address of the SVC processor, the address of the RIB, and how much 
information to supply to the SVC processor. Table 4-1 explains the format of an RDB. 


Table 4-1. Request Definition Block (RDB) Format 


Field Size 

Contents 

Word 

Flags, > 1000 for user-defined SVCs 

Word 

Address of the SVC processor 

Word 

Address of the RIB for this SVC (zero If no RIB is defined) 

Word 

Size of the call block in bytes 

Byte 

Number of bytes of the call block to be copied by DNOS for the 

SVC processor (starting at byte 0) 

Byte 

Zero 

Word 

Zero 


Figure 4-1 shows several RDB definitions for user-defined SVCs. 

The operating system uses an RIB to return data from the system copy of the call block to the call- 
ing task. If only the error byte of the call block is returned, no RIB is needed. An RIB must be speci- 
fied in the RPUDAT module when any other information is to be returned. Table 4-2 shows the 
format of an RIB. The pair of byte fields can be repeated If information is to be returned from sev- 
eral noncontiguous areas in the call block. 
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THIS MODULE HAS THE DATA TABLES TO ENABLE PROCESSING OF 
USER-DEFINED SVCS. RPUTAB IS THE TABLE OF RDB AND PROCESSOR 
ADDRESSES FOR THE SVCS. THE SET OF RDB DEFINITIONS FOLLOWS, 
AND RIB DEFINITIONS ARE INCLUDED FOR RELEVANT CASES. IN 


★ ADDITION, 

RPUMAX 

IS DEFINED TO BE THE MAXIMUM USER-DEFINED 

★ SVC 

CODE. 




IDT 

' RPUDAT 

1 


DEF 

RPUMAX 

, RPUTAB LABELS TO ACCESS USER DATA 


REF 

SVC080 

,SVC082 LABELS OF ENTRY POINTS 

RPUTAB 

DATA 

>E000 

SVC80 - FIND CPU TIME 


DATA 

RDBU80 



DATA 

0 

SKIP SVC81 


DATA 

0 



DATA 

>E000 

SVC82 - SPECIAL ADD 


DATA 

RDBU82 


RPUMAX 

BYTE 

>82 

MAXIMUM USER-DEFINED CODE 

RDBU80 

DATA 

>1000 

FLAGS 


DATA 

SVC080 

PROCESSOR 


DATA 

RIBU80 

RETURN INFORMATION BLOCK 


DATA 

6 

MAXIMUM CALL BLOCK SIZE 


BYTE 

2 

COPY ONLY TWO BYTES 


BYTE 

0 

RESERVED 


DATA 

0 

RESERVED 

RDBU82 

DATA 

>1000 

FLAGS 


DATA 

SVC082 

PROCESSOR 


DATA 

RIBU82 

RETURN INFORMATION BLOCK 


DATA 

16 

MAXIMUM CALL BLOCK SIZE 


BYTE 

16 

COPY ALL 


BYTE 

0 

RESERVED 


DATA 

0 

RESERVED 

RIBU80 

DATA 

0 

RESERVED 


BYTE 

2,4 

START AT OFFSET 2, RETURN 4 BYTES 


DATA 

0 

RESERVED 

RIBU82 

DATA 

0 

RESERVED 


BYTE 

2,6 

START AT OFFSET 2, RETURN 6 BYTES 


BYTE 

12,4 

AND AT OFFSET 12, RETURN 4 BYTES 


DATA 

0 



END 




Figure 4-1. Format of RPU DAT Module 
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Table 4-2. RIB Format 


Field Size 

Contents 

Word 

Zero 

Byte 

Offset in the call block from which the return of data should begin 

Byte 

Number of bytes to return 

Word 

Zero 


Figure 4-1 shows a source module for defining two user SVCs using SVC opcodes >80 and >82 
with opcode >81 omitted. 

4.2.3 SVC Processor Details 

The SVC processor must define its own entry point in a DEF directive. It must save and restore 
system registers by using two macro cails: SPUSH 1 as the first instruction and SPOP 1 as the last 
instruction. The processor runs as part of the operating system kernei, making use of an operating 
system workspace. Upon entry to the processor, the following registers are set: 

• Register 1 — Points to the system copy of the requesting call block 

• Register 4 — Points to the requester task status block (TSB) 

• Register 5 — Points to the requester-saved map file 

• Register 10 — Points to an internai operating system stack 

• Register 13 — Requesting task workspace pointer 

• Register 14 — Requesting task program counter 

• Register 15 — Requesting task status register 
The SVC processor must not aiter registers 10, 13, 14, and 15. 

Register 1 contains the address of the system copy of the requester’s call block. The processor 
usually gathers all the information it needs from this copy. The processor alters the copied call 
block to pass information back to the requesting task. The second byte of the call block should 
always be used for returning a status code. If necessary, the processor can also access the 
requester task area to get or return data using long distance instructions, with register 5 as the 
map fiie pointer. 

When the processor finishes its work, it must return to the operating system by issuing the 
foliowing: 

CLR RO 
SPOP 1 
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The operating system then returns information as specified in the RIB for the SVC performed. 
Finally, control passes back to the task that Issued the SVC. 

Figure 4-2 shows a processor for user-defined SVC >80, corresponding to the definitions in 
Figure 4-1. 


TITL 'SVC080 PROCESSOR — GET EXECUTION TIME' 


★ THIS EXAMPLE PROCESSOR IS FOR USER-DEFINED SVC >80. IT * 

★ RETURNS THE AMOUNT OF CPU TIME USED BY THE TASK SO FAR. ★ 

★ IT ACCESSES THE FIELD “TSBCPT" IN THE TSB. * 


* THE 

■k 

CALL 

BLOCK 

HAS THE 

FORM: 

ic 

00 

! 

80 

! ERROR CODE 

* 

02 

! 

TIME 

EXECUTING SO FAR 

★ 

04 

! 

IN INTERNAL CLOCK TICKS 

★ 






* 


* 


★ 


★ UPON ENTRY R1 POINTS TO THE COPY OF THE CALL BLOCK 

* R4 POINTS TO THE TSB OF THE REQUESTER 


IDT 'SVC080' 

DEF SVC080 ENTRY POINT 

LIBIN DSC .MACROS .TEMPLATE TO USE TSB EQUATES 
COPY DSC .TEMPLATE. ATABLE. TSB ... 


LIBIN DSC .MACROS . FUNC 
SVC080 EVEN 

SPUSH 1 

MOV aTSBCPT(R4) ,a2(R1) 
MOV aTSBCPT+2 (R4) , a4(Rl) 
CLR R2 

MOVB R2,ai (R1 ) 

CLR RO 
SPOP 1 
END 


FOR OS FUNCTIONS 

SAVE RETURN ADDRESS 
MOVE EXECUTION TIME 
. . . INTO CALL BLOCK 
GET A ZERO 
SHOW NO ERROR 
PREPARE FOR RETURN 
RETURN TO DNOS 


Figure 4-2. User- Defined SVC 
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4.2.4 System Generation Requirements 

To Include user-defined SVCs, specify the pathname of the RPUDAT object module In response to 
the following request during system generation: 

USER SVC TABLE PATHNAME: 

In addition, place the object module for each user-defined SVC processor in a directory called 
.S$OSLINK.S$SGU$.USERSVC on the data disk used during system generation. This directory is 
treated as a library when the system is linked; consequently, the processor entry point name must 
be the same as the file name of the appropriate module In the .S$OSLINK.S$SGU$.USERSVC 
directory. If a file has several SVC processors in it, each processor entry point name must be listed 
as either an alias or a file name in the .S$OSLINK.S$SGU$.USERSVC directory. 


4 
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5.1 INTRODUCTION 

Although DNOS supports a variety of peripheral devices, some users find it necessary to add a 
device not supported by the standard software. This section presents a method for writing soft- 
ware to support a nonstandard device. 

The software that controls a peripheral device Is called a device service routine (DSR). This sec- 
tion supplies information to assist you in writing a DSR for DNOS. The ideas and materials pre- 
sented are taken directly from the DSRs for the standard devices supported by DNOS. The 
examples apply to devices connected either through the communications register unit (CRU) or 
through the TILINE. (TILINE is a registered trademark of Texas Instruments Incorporated.) The 
CRU Is a low-speed, bidirectional, serial data bus. The TILINE is a high-speed, bidirectional, 
parallel data bus. 

This section describes the DNOS I/O subsystem, DSR support routines, and DSR data structures. 
This section also tells how to write DSRs for asynchronous controllers. These descriptions are not 
comprehensive; they apply specifically to the problem of writing a DSR to support a nonstandard 
device. Refer to the DNOS System Design Document for further details and diagrams of data 
structures discussed in this section. 


5.2 PREPARATION 

To write a DSR, you should be familiar with the following areas: 

• Hardware interface for the device 

• DNOS I/O subsystem 

• Basic data structures 

• Computer hardware 

• Assembly language 

You should also study the process of system generation. Although this information is only indi- 
rectly related to writing a DSR, it provides insight into how the operating system interfaces with a 
DSR. 

To help you locate the appropriate material, the following paragraphs describe the I/O subsystem 
and the basic data structures. 
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5.3 I/O SUBSYSTEM 

The I/O subsystem moves data between any combination of logical and physical I/O resources 
and programs (tasks) that process the data. A DSR is concerned with the path between the pro- 
gram and the physical I/O resource (that is, the device). 

5.3.1 Data Structures 

The following templates define the data structures that relate to writing a DSR. To use one of 
these templates, Insert a COPY statement in the source. 

In all the data structure pathnames, DSC is a synonym that must be assigned the value of 
< volume>.S$OSLINK, where volume is the name of the data disk used for system generation. 
You can examine any of these structures by printing the appropriate file from the DNOS release 
disk. 


Template 

DSC.TEMPLATE.ATABLE.BRO 

DSC.TEMPLATE.ATABLE.CDE 

DSC.TEMPLATE.ATABLE.IRB 

DSC.TEMPLATE.ATABLE.PDT 

DSC.TEMPLATE.ATABLE.KSB 

DSC.TEMPLATE.ATABLE.XTK 

If you use the KSB and XTK templates in 
statements: 


Contents 

Buffered request overhead 
Command definition entry 
I/O request block (IRB) 

Peripheral device table (PDT) 

Keyboard status block (KSB) 

Keyboard extension 

the DSR, you must include the following EQU 


KSBBGN EQU PDTSIZ Precedes KSB copy 

XTKBGN EQU KSBSIZ Precedes XTK copy 


If you are writing a DSR for an asynchronous controller that is to be used with standard DSRs for 
asynchronous controllers, you must use the following templates: 

Template Contents 


DSC.TEMPLATE.ATABLE.DSALLLEX 
DSC.TEMPLATE.ATABLE.DSALLREX 
DSC.TEM PLATE. ATABLE.AJ M PM AC 


Asynchronous local extension 
Asynchronous remote extension 
Subroutine references for an 
asynchronous hardware service 
routine (HSR). 
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The following templates define word and byte constants available to the DSR: 

Template Defined Constants 


DSC.TEMPLATE.COMMON.NFEROO 

DSC.TEMPLATE.COMMON.NFER10 

DSC.TEMPLATE.COMMON.NFER20 

DSC.TEMPLATE.COMMON.NFER30 

DSC.TEMPLATE.COMMON.NFER40 

DSC.TEMPLATE.COMMON.NFER50 

DSC.TEMPLATE.COMMON.NFER60 

DSC.TEMPLATE.COMMON.NFER70 

DSC.TEMPLATE.COMMON.NFER80 

DSC.TEMPLATE.COMMON.NFER90 

DSC.TEMPLATE.COMMON.NFERAO 

DSC.TEMPLATE.COMMON.NFERBO 

DSC.TEMPLATE.COMMON.NFERCO 

DSC.TEMPLATE.COMMON.NFERDO 

DSC.TEMPLATE.COMMON.NFEREO 

DSC.TEMPLATE.COMMON.NFERFO 

DSC.TEMPLATE.COMMON.NFWORD 


BYTEOO-BYTEOF 

BYTE10-BYTE1F 

BYTE20-BYTE2F 

BYTE30-BYTE3F 

BYTE40-BYTE4F 

BYTE50-BYTE5F 

BYTE60-BYTE6F 

BYTE70-BYTE7F 

BYTE80-BYTE8F 

BYTE90-BYTE9F 

BYTEAO-BYTEAF 

BYTEBO-BYTEBF 

BYTECO-BYTECF 

BYTEDO-BYTEDF 

BYTEEO-BYTEEF 

BYTEFO-BYTEFF 

WD0001-WD8000 & MASTAB 


The following template contains the pointers to Items relevant to the operating system: 

DSC.TEMPLATE.COMMON.NFPTR Pointer segment 

To assemble templates, you need a set of macros. You can access them by means of a LIBIN 
statement using the following pathnames: 

DSC. MACROS.TEM PLATE 
DSC.MACROS.FUNC 

In addition to the system-defined data structures, you can design your own data structure, called 
the device information block (DIB). To access this structure, use workspace register 4 of the physi- 
cal device table (PDT). You should set the origin of the DIB to follow the PDT and any system data 
structures that follow the PDT. The DIB includes any data you wish to access or maintain by using 
the DSR. 

5.3.2 Request Flow 

An I/O request enters the I/O subsystem via the supervisor call (SVC) interface. The SVC interface 
decodes the request and passes it to the I/O subsystem. Routing information is derived from the 
logical unit number (LUNO) in the I/O request block (IRB). The I/O system checks the access privi- 
lege to the physical resource. Routing data and requester identifiers are concatenated to the IRB 
to form the buffered request block (BRB). The I/O subsystem passes the BRB to the device 
manager. 

The device manager examines the operation code of each request and processes each accord- 
ingly. The device manager processes operation codes >00, >03, >05, >09, >0A, >0B, and >0C. 
The Open operation codes > 00 and > 03 are checked only for terminals (keyboard devices that use 
a KSB). The device manager verifies the request buffer and aliocates table space in the buffer 
table area (BTA) for the read operation codes > 05, > 09, and > OA. 
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For write operation codes > OB and >0C, the device manager copies the data buffer into the BTA 
after verifying the buffer and allocating space as for read operations. Bits DSFBI and DSFBO in 
the PDT control allocation of the BTA for each device. The device manager then places the request 
on a queue associated with the PDT and passes control to the DSR, which processes the request 
immediately or after completing any prior requests. 

While the DSR is processing a request but waiting for an Interrupt, control returns to the operating 
system. The system executes programs during this time until the DSR receives an interrupt. An 
interrupt returns control to the DSR for further processing. 

When the DSR terminates the current request, the next request (If any) is passed to the DSR. The 
completed request Is placed in a queue related to the program. The next time the program exe- 
cutes, the completed request is returned to the program. This completes the cycle for an I/O 
request. 

5.3.3 Device Interrupt Decoder 

After the DSR initiates the device operation associated with the request, control returns to the 
system until an interrupt from the device causes the DSR to resume processing the request. 
Therefore, the programmer who is writing the DSR should know how the system uses the system 
interrupt decoder to process an interrupt. 

The interrupt decoder loads the DSR map file and transfers control to the DSR for the interrupting 
device. The methods of handling interrupt signals are as follows: 

• Single device per interrupt level 

• Multiple devices per interrupt level 

• Multiple devices in an expansion chassis 

• Single device or multiple devices on a multiplexed device controller 

Subsequent paragraphs describe typical system-interrupt decoder routines. The system 
generation process builds these routines, and users cannot modify them. 

5.3.3.1 Single-Device Interrupt. Figure 5-1 shows an example of the interrupt decoder for a 
single device at Interrupt level 13. The workspace address (WSPD) and the interrupt decoder exe- 
cution address (PCS) are stored at locations >34 and >36, respectively. The first six registers (RO 
through R5) of the workspace are not used. Register R6, which Is the service flag, is set to 1, and 
register R7 contains 0. Register R8 contains WPdsr, the address of the workspace for the DSR. 
Register R9 contains SG3BGN, the execution address of the interrupt service routine (ISR) within 
the DSR. Register RIO contains MPdsr, the address of the map file for the DSR. 
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DATA WSPD,PCS LOCATION >34 AND >36 


EQU 

$-12 


R0-R5 

DATA 

1 ,0, WPdsr, S63BGN 

, MPdsr 

INPRPT ENTRY 

DATA 

0,0, 0,0,0 


R11-R15 

MOV 

aCURMAP, R1 1 

SAVE 

CURRENT MAP FILE 

MOV 

R10,aCURMAP 

SET UP DSR MAP FILE 

LMF 

R10,0 



BLUP 

R8 

ENTER 

DSR 

JMP 

RETURN 




Figure 5-1. Interrupt Decoder for Single Device 


When an interrupt occurs, the current status is saved in registers R13, R14, and R15 of WSPD. The 
interrupt decoder begins execution by saving the current map fiie address in register R1 1 . The rou- 
tine pieces the address of the DSR map file in location CURMAP. The DSR map file is loaded and 
control is transferred to the ISR. On return from the ISR, the interrupt decoder branches to a return 
routine at location RETURN. 

5.3.3.2 Multiple-Device Interrupt. Figure 5-2 shows an example of the interrupt decoder for mul- 
tiple devices at interrupt level 10. Locations >28 and >2A contain the address of the workspace 
(WSPA) and the interrupt decoder execution address (PCM), respectively. The first six registers (RO 
through R5) of the workspace are not used. Register R6, which is set to 0 initially, is the service 
flag. It is set to 1 at the completion of the servicing of the interrupt. Register R9 contains the 
address of a table (TABLA) that contains pairs of words. The table has extra pairs for additional 
devices and is terminated by a word that contains 0 (DATA 0). The first word of each pair contains 
the CRU address of the bit that tells you which device caused the interrupt. The second word of 
the pair is the address of a three-word data structure (IVxxOI or IVxx02) that contains the work- 
space address (WPdsr), the execution address (SG3BGN), and the map file address (MPdsr) for the 
ISR. 


2270510-9701 


5-5 



Writing a DSR 



DATA 

WSPA , PCM 

LOCATION >28 AND >2A 

WSPA 

EQU 

$-12 

RO -R5 


DATA 

0,0,0, TABLA, 

0,0, 0,0, 0,0 R6-R15 

TABLA 

EQU 

$ MULTIPLE INTERRUPT DECODER TABLE 


DATA 

<cru interrupt bit address> 


DATA 

I Vxx01 



DATA 

<cru interrupt bit address> 


DATA 

I Vxx02 



DATA 

0 LOGICAL END OF TABLE 

I Vxx01 

DATA 

KBdsr,SG3BGN 

,MPdsr 

I Vxx02 

DATA 

KBdsr , SG3BGN 

, MPds r 

PCM 

MOV 

aCURMAP, R11 

SAVE CURRENT MAP FILE POINTER 


MOV 

R9, R8 

GET THE TABLE ADDRESS 


CLR 

R6 

SET SERVICE FLAG TO ZERO 

PCM1 0 

MOV 

*R8+, R1 2 

IS THE TABLE EXHAUSTED? 


J EQ 

RETURN 

AND EXIT 


TB 

0 

DID THIS GUY DO IT? 


JNE 

PCM20 

NOT I, SOMEONE ELSE DID IT 


MOV 

*R8, R7 

GET ENTRY VECTOR 


MOV 

a4(R7) , R1 0 

PICK UP THE NEW MAP ADDRESS 


MOV 

R1 0,aCURMAP 

CHANGE MAPS 


LMF 

R10,0 



BLWP 

*R7 

ENTER THE DSR 


SETO 

R6 

INDICATE AN INTERRUPT SERVICED 

PCM20 

INCT 

R8 

NEXT TABLE ENTRY 


JMP 

PCM1 0 




Figure 5-2. 

Interrupt Decoder for Multiple Devices 
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When an interrupt occurs, the current status is saved in registers R13, R14, and R15 of WSPA. The 
interrupt decoder begins execution by saving the current map file pointer in register R11. The 
decoder then moves the address of table TABLA into register R8 and clears the service flag in reg- 
ister R6. The device interrupt bit must be tested to determine if the device Interrupted. The CRU 
address of this device is moved into register R12. If the address is 0, the interrupt decoder 
branches to the return code. Otherwise, the device Interrupt bit is checked. If it is 0, the next 
device interrupt bit is checked. A nonzero value identifies the Interrupting device, and the address 
in the next word (IVxxOI or IVxx02) is moved into register R7. The DSR map file address is moved 
into register R10. The routine then moves the DSR map file address Into location CURMAP, loads 
the map file, and branches to the ISR. When the ISR returns control to the interrupt decoder, the 
interrupt decoder checks the remaining devices in TABLA for interrupts. 

5.3.3.3 Expansion Chassis Interrupt. Figure 5-3 shows an example of the interrupt decoder for 
devices in the expansion chassis on the first expansion card at interrupt level 7. Locations > 1C 
and >1E contain the address of the workspace {WSP7) and the interrupt decoder execution 
address (PCE), respectively. The first six registers (RO through R5) of the workspace are not used. 
Registers R6 and R1 2 contain the CRU base address of the expansion card. 

Location EXPTST contains the first of a table of mask words that correspond to flag bit positions 
for the expansion chassis. Table ETAB contains the address (CTAB1) of a table for the first expan- 
sion chassis on the first card. Table CTAB1 contains addresses of three-word data structures 
(IVxx03 or IVxx02) that contain the workspace address (WPdsr), the execution address (SG3BGN), 
and the map file address (MPdsr) for the ISRs. The table also contains the address of a table 
(IVX110) for multiple devices on the same interrupt position and a flag word for each address in the 
table. The flag for each address follows the address. It is set to 0 for three-word data structure 
addresses and to - 1 for the multiple device table address. The multiple device table contains 
CRU addresses for the interrupt bits and addresses of three-word data structures (IVxx04 and 
IVxx05) for ISRs for those devices. 


WSP7 


EXPTST 


ETAB 


DATA WSP7,PCE LOCATION >1 C AND >1E 


EQU $-12 RO -R5 

DATA >1F00,0,0,0,0,0,>1F00, 0,0,0 R6 -R1 5 


DATA >4000, >2000, >1 000, >800 TEST BIT FOR EXP CHASSIS 


EQU $ EXPANSION CHASSIS TABLE 

DATA CTAB1 ,0,0, 0,0, 0,0,0 


Figure 5-3. Expansion Chassis interrupt Decoder (Sheet 1 of 3) 
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IVX1 1 0 


CTAB1 


I Vxx03 
I Vxx04 
I VxxOS 
IVxx02 


EQU $ 

DATA >051E 
DATA IVxxOA 
DATA >053E 
DATA IVxxOS 

DATA 0 LOGICAL END OF TABLE 

EQU $ 

DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA IVxx03,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA IVX110,-1 
DATA 0,0 
DATA 0,0 
DATA IVxx02,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 
DATA 0,0 


DATA KBdsr,SG3BGN,MPdsr 
DATA KBdsr,SG3BGN,MPdsr 
DATA KBdsr, SG3BGN,MPdsr 
DATA WPdsr,SG3BGN,MPdsr 


Figure 5-3. Expansion Chassis interrupt Decoder (Sheet 2 of 3) 
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PCE 

EQU 

$ 


MOV 

aCURMAP, R1 1 

PCE1 0 

STCR 

R9,0 


MOV 

R9,R10 


SRL 

R1 0 ,6 


ANDI 

R10,6 


COC 

aEXPTST(RIO) ,R9 


JEQ 

IX 


A 

R8,R10 


MOV 

aETAB<R10) ,R10 


J EQ 

IX 


ANDI 

R9,>7C 


A 

R9, R1 0 


MOV 

*R10+,R9 


J EQ 

IX 


MOV 

*R1 0 , R7 


JNE 

PCE20 


MOV 

a4(R9) ,R10 


MOV 

R1 0,aCURMAP 


LMF 

R10,0 


BLWP 

*R9 

PCE1 5 

MOV 

R6, R1 2 


TB 

15 


JEQ 

PCE1 0 


JMP 

RETURN 

PCE20 

MOV 

*R9+,R12 


JEQ 

PCE1 5 


MOV 

*R9+, R7 


TB 

0 


JNE 

PCE20 


MOV 

a4<R7) , R1 0 


MOV 

R10,aCURMAP 


LMF 

R10,0 


BLWP 

*R7 


JMP 

PCE20 


EXPANSION CHASSIS ENTRY 
SAVE CURRENT MAP FILE POINTER 
FIND CHASSIS THAT INTERRUPTED 


IS THAT CHASSIS PRESENT? 

NO, CRASH ! ! ! 

ADD CARD LEVEL 

IS THE CHASSIS DEFINED? 

NO, TAKE IT DOWN 
INTERRUPT POSITION 
INDEX INTO TABLE 
INTERRUPT POINTER 
NOTHING THERE 
CHECK FLAG 

MULTIPLE DEVICES THERE 
DSR MAP BECOMES CURRENT MAP 


ENTER THE DSR 
RESTORE THE CARD BASE 
ANY MORE INTERRUPTS? 

YES, GET THEM NOW 
OTHERWISE, EXIT 

END OF TABLE? 

YES, BACK TO THE CARD LEVEL 
GET THE ENTRY VECTOR 
IS THIS IT? 

NO, KEEP LOOKING 
PICK UP MAP POINTER 
CHANGE MAPS 

ENTER THE DSR 


Figure 5-3. Expansion Chassis interrupt Decoder (Sheet 3 of 3) 
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When an interrupt occurs, the current status is saved in registers R13, R14, and R15 of WSP7. The 
interrupt decoder begins execution by saving the current map file address in register R11. The 
interrupt decoder reads the expansion coupler status word into register R9. The decoder calcu- 
lates the ID of the interrupting chassis (times 2) in register RIO. Using a mask from table EXPTST, 
the decoder verifies that the expansion chassis is connected. If it is not, the interrupt decoder 
branches to the illegal interrupt routine. 

Register R10 is then used to index into the table ETAB to get the address of the chassis table. If 
the pointer is 0, the interrupt decoder branches to the illegal Interrupt routine. If not, the device 
interrupt position is added to the chassis table address to obtain the index of the address corre- 
sponding to the interrupt position in the chassis table. If the address is 0, the interrupt decoder 
branches to the illegal interrupt routine. If not, the decoder tests the flag associated with the 
address. 

If this flag is a nonzero value, the decoder branches to location PCE20 to process multiple 
devices. If the flag is 0, the decoder moves the DSR map file pointer into register R10 and into the 
current map file pointer, CURMAP. The decoder loads the DSR map file and transfers control to 
the ISR. When control returns from the ISR, the decoder restores the proper CRU address in regis- 
ter R12 and tests the expansion chassis interrupt bit for another interrupt. When another interrupt 
exists, the decoder branches to location PCE10 to decode the outstanding interrupt. Otherwise, 
the decoder branches to the return code. 

The multiple-device routine at location PCE20 is similar to the routine described in the preceding 
paragraph. It loads the CRU address and tests for 0 at the end of the table. Then, the routine loads 
the data structure address corresponding to the CRU address. The routine tests the interrupt bit 
and returns to location PCE20 when the bit is 0. When the Interrupting device is located, the rou- 
tine loads the map file and transfers control to the ISR as previously described. On return from the 
ISR, the routine branches to location PCE20 to process any additional interrupt at the interrupt 
position. 

5.3.3.4 Asynchronous Multiplexer Interrupt Decoder. Use this decoder for CI403 and CI404 
multiplexers in the following cases: 

• They use a single interrupt. 

• They share interrupts in the main chassis. 

• They share interrupts in the expansion chassis. 

Figure 5-4 shows an example of the interrupt decoder for devices on a multiplexer(s) that has an 
interrupt level of 11 in the main chassis. Location >2C contains the address of the workspace 
(WSPB) and location > 2E contains the decoder entry point (PCA). The decoder uses the first three 
registers (RO through R2 of WSPB) to pass controller information to the asynchronous DSR. In 
RIO, there is a pointer to the controller table(s) (ACTLB) which the system generation builds for 
each controller that shares an interrupt level of 11. The decoder places the TILINE address of the 
controller in R12 and uses the remaining registers as temporary registers. 

Location ACTLB contains three word (word 0 through word 2) of controller information for each 
controller that shares interrupt level 11. The table is terminated with a zero. Word 0 contains the 
TILINE address of the controller. Word 1 is a pointer to the channel table (MUXB01). Word 2 is the 
result of taking the maximum channel number of the controller and multiplying that number by 
eight. 
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Location MUXB01 contains four words (word 0 through word 3) of information for each channel of 
the controiier (for a channei that was not specified during system generation, the four words asso- 
ciated with the channei each contain zero). Word 0 of the channel table contains a pointer to the 
DSR interrupt workspace (KBdsr). Word 1 contains the DSR address (SG3BGN). Word 2 contains a 
pointer to the DSR map fiie (MPdsr). Word 3 contains the channel number. 



DATA 

WSPB, PCA 

LOCATION >2C,>2E 

USPB 

BSS 

20 

RO R9 


DATA 

ACTLB-4 

RIO -- CONTROLLER TABLE ADDRESS 


BSS 

10 

R11 -- R15 

ACTLB 

EQU 

$ 

MULTIPLE INTERFACE TABLE 


DATA 

>F980 

MUX INTERRUPT WORD ADDRESS 


DATA 

MUXB01 

MUX CHANNEL TABLE ADDRESS 


DATA 

3*8 

MAX MUX CHANNEL ID * 8 


DATA 

0 

LOGICAL END OF TABLE 

MUXB01 

EQU 

$ 

CHANNEL TABLE 


DATA 

KBdsr, SG3BGN, 

MPdsr ,0 


DATA 

KBdsr, SG3BGN, 

MPds r , 1 


DATA 

0, 0, 0, 0 

DUMMY CHANNEL ENTRY 


DATA 

0 , 0 , 0 , 0 

DUMMY CHANNEL ENTRY 

SLW3 

EQU 

R3*2 

SLAVE WORD THREE ADDRESS 

PCA 

MOV 

aCURMAP, R1 1 

SAVE CURRENT MAP FILE 


MOV 

R10,R9 

GET CONTROLLER TABLE ADDRESS 

PCA01 5 

AI 

R9,4 

GET CONTROLLER TABLE ENTRY 

PCA020 

MOV 

*R9+, R1 2 



J EQ 

PCARTN 

IF TABLE EXHAUSTED, EXIT 


JGT 

PCA01 5 

IF CONTROLLER NOT PRESENT, NEXT CONTROLLER 


SETO 

R4 

SET LOAD MAP FILE FLAG 


MOV 

*R1 2, R8 

DID THIS CONTROLLER DO IT? 


JGT 

PCA01 5 

NO -- NEXT CONTROLLER 


MOV 

*R9+, R7 

GET STATION LIST ADDRESS 


MOV 

*R9+ , R6 

GET CHANNEL COUNT (C0UNT*8) 

PCA025 

MOV 

aSLW3 (R1 2) , RO 

IS THE INTERRUPT INVALID? 


J LT 

PCA020 

YES -- NEXT CONTROLLER 


MOV 

R 0 , R 1 

SAVE DATA WORD 


MOV 

RO, R2 

SAVE DATA WORD 


MOV 

R4, R4 

RELOAD MAP FILE? 


J LT 

PCA027 

YES -- DON'T TEST FOR SAME CHANNEL 


CZC 

aWD0800, RO 

SAME CHANNEL? 


JEQ 

PCA027 

YES 


SETO 

R4 

FORCE MAP FILE LOAD 


Figure 5-4. Asynchronous Multiplexer Interrupt Decoder (Sheet 1 of 2) 
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PCA027 

SLA 

o 

00 

MOVE DATA TO LEFT BYTE 


SRL 

R1 ,12 

STATUS CODE TO BITS 13,14,15 


Cl 

R1 ,>0004 

TIMER OR TRANSPARENT FIFO STATUS? 


JEQ 

PCA050 

YES -- PROCESS 


SRL 

R2,5 

8 * CHANNEL NUMBER 


ANOI 

R2,7*8 

ISOLATE CHANNEL NUMBER * 8 


C 

R2, R6 

ADDRESS OUT OF RANGE? 


JH 

PCA1 00 

YES -- ILLEGAL CHANNEL NUMBER 


MOV 

R7, R8 

SAVE CHANNEL TABLE ADDRESS 


A 

R2, R8 

GET CHANNEL ENTRY VECTOR ADDRESS 


MOV 

a4<R8) , R5 

GET MAP FILE ADDRESS 


JEQ 

PCA025 

IF CHANNEL NOT GENNED, NEXT CHARACTER 


ABS 

R4 

CHANGE MAP FILE? 


JGT 

PCA028 

NO 


MOV 

R5,aCURMAP 

YES -- SET MAP FILE POINTER 


LMF 

R5 ,0 

LOAD DSR MAP FILE 

PCA028 

BLWP 

*R8 

ENTER DSR 


JMP 

PCA025 

TRY THIS CONTROLLER AGAIN 

PCA050 

CLR 

R2 

CLEAR CHANNEL NUMBER 


JMP 

PCA060 

BYPASS CHANNEL INCREMENT 

PCA055 

AI 

R2,1*8 

GET NEXT CHANNEL ENTRY 


C 

R2 , R6 

ADDRESS OUT OF RANGE? 


JH 

PCA11 0 

YES -- CHECK CONTROLLER AGAIN 


LI 

R1 ,>0004 

RELOAD STATUS CODE 

PCA060 

MOV 

R7, R8 

SAVE CHANNEL TABLE ADDRESS 


A 

R2,R8 

GET CHANNEL ENTRY VECTOR ADDRESS 


MOV 

a4(R8) , R5 

GET MAP FILE ADDRESS 


JEQ 

PCA055 

IF CHANNEL NOT GENNED, NEXT CHANNEL 


MOV 

R5,aCURMAP 

SET MAP FILE POINTER 


LMF 

R5,0 

LOAD DSR MAP FILE 


BLWP 

*R8 

ENTER DSR 


JMP 

PCA055 

NEXT CHANNEL 

1 CA1 00 

EQU 

$ 

ILLEGAL CHANNEL NUMBER 


INC 

R3 

INCREMENT NUMBER OF ILLEGAL INTERRUPTS 

PCA1 1 0 

SETO 

R4 

SET CHANGE MAP FILE FLAG 


JMP 

PCA025 

NEXT CONTROLLER 


Figure 5-4 Asynchronous Multiplexer Interrupt Decoder (Sheet 2 of 2) 


When an interrupt occurs, the present status Is saved in R13, R14, and R15 of WSPB. When the 
interrupt decoder begins execution, it saves the current map file address by placing it in R11. The 
interrupt decoder searches for the controller which generated the interrupt by placing Word 0 of 
the controlier information table (ACTLB) into R12 and then reading slave word 0 of the TPCS. The 
controller that has an interrupt pending will have a negative value in slave word 0. Once the 
decoder finds the controller with the interrupt pending, it looks at word 1 of the appropriate con- 
troller table to find the pointer to the channel tables (MUXB01). This pointer indicates where the 
DSRs for each channel are located. The decoder then determines which channel caused the inter- 
rupt and picks up the proper channel DSR mapfile (MPdsr) and loads it. The decoder enters the 
DSR by executing a Branch and Link Workspace Pointer (BLWP) instruction, using the DSR work- 
space (KBdsr) and program address (SG3BGN). When the DSR returns control to the interrupt 
decoder, the Interrupt decoder checks the remaining controllers at ACTLB for pending interrupts. 
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5.3.3.5 Return Routine. The return routine in Figure 5-5 tests the service flag and branches to 
the Illegal interrupt routine when the flag Is 0, indicating that no Interrupt has been serviced. 
Otherwise, the routine moves the saved map file address to location CURMAP and loads the map 
file. It transfers to a routine at location NFTRTN that checks processing conditions and executes 
a Return to Workspace Pointer (RTWP) instruction. This restores the machine status to its 
pre-interrupt status. 


RETURN 

MOV 

R6, R6 

TEST SERVICE FLAG 


JEQ 

IX 

NOTHING SERVICED IS AN ERROR 

PCARTN 

MOV 

R1 1 ,aCURMAP 

RESTORE OLD MAP FILE POINTER 


LMF 

R11 ,0 

RESTORE OLD MAP 


B 

aNFTRTN 

RETURN TO OS 



Figure 5-5. Interrupt Decoder Return Routine 


5.3.3.6 Illegal Interrupt Routine. The illegal interrupt routine in Figure 5-6 stores the status reg- 
ister contents in register R11 and caiculates the ievei of the illegai interrupt. The routine then 
moves the ievei into location LEVEL to form the crash code; finaiiy, the routine branches to the 
system crash routine using the transfer vector at location NFCRSH. 


IX 


LEVEL 


STST 

R1 1 




ANDI 

R1 1 , 

r> 

F 


INC 

R1 1 



R1 1 = 

SOC 

R1 1 < 

r 3 

LEVEL 


BLWP 

aNF( 

:r 

SH 

BOGUS 

DATA 

>10 



CRASH 


BAD INTERRUPT LEVEL 

INTERRUPT CRASH 

CODES >13 1 F 


Figure 5-6. Illegal Interrupt Routine 


5.4 DEVICE SERVICE ROUTINES 

The following paragraphs describe DSRs, including their design criteria. Figure 5-7 shows the 
overall organization of a DSR that interfaces directly between a device and DNOS. A DSR that 
Interfaces between an asynchronous controller and DNOS can be structured according to Figure 
5-8. Any unique properties of this type of DSR are described in a iater description of DSRs for asyn- 
chronous devices. 
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227942 1 


Entry Points 
Sub-Opcode Decoder 


Sub-Opcode Processing 
Routines 


End-of-Record Routine 
Time-Out Routine 


Abort Routine 
Power On Routine 


Reentry Routine 
Hardware Interrupt Routines 


Figure 5-7. DSR Structure 


The entry points to the DSR are described first, along with the routines to which they branch the 
body of the DSR (the subopcode decoder, the subopcode processing routines, and the end-of- 
record routine) is described next. The set of DSR support routines that the DSR can call when 
required is described last. 

5.4.1 Design Criteria 

To service multiple devices of the same type on the same system, you must design the code of the 
DSR to be shared and reentrant. The DSR must service each interrupt very quickly. It must appear 
to service multiple device interrupts simultaneously. However, only one interrupt at an interrupt 
level can be serviced at one time. Subsequent Interrupts must wait for servicing until the current 
one has completed. 

Each PDT maintains information about a single physical device for the I/O subsystem, and each 
physical device requires a PDT. Part of the PDT is the DSR workspace. Between the processing of 
requests for the device and interrupts from the device, data is stored either in the PDT workspace 
registers or in extensions to the PDT. Use registers R1 through R4 and R12 through R15 of the PDT 
only for their intended purposes, as described in the PDT template. The following registers are 
available for exclusive DSR use: RO and R5 through R11. 
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The DIB is the extension storage area of the PDT. Any data stored in the DSR can be destroyed as 
the DSR services other devices. Even if your present'configuration has only one device for which 
you are writing the DSR, you should provide for possible expansion to several of these devices. 
The DSR should not modify any of the DSR code. 

The keyboard status block (KSB) maintains device information for keyboard devices. If you answer 
YES to the KEYBOARD? prompt during system generation of special devices, your device is gener- 
ated as a keyboard device. In this case, you must include a KSB as the first part of the DIB. The 
KSBSN field in your KSB is initialized to your station number by system generation. (All devices 
with a keyboard are given device names that have the form STxx.) 

The KSB contains the DSR interrupt workspace for keyboard devices. Like the PDT, the KSB can 
be extended. The XTK is an example of a KSB extension. 

Figure 5-8 shows the logical structure of the DSR in relationship to the operating system. Model 
990 Computer hardware maps memory in three segments defined in a map file: 

• Interrupt trap addresses and system root (first segment) 

• Data buffer (second segment) 

• DSR (third segment) 

The upper limit of the first segment is shown as XXXX because the size of this segment varies. 
This value is defined during system generation and can be found in JCASTR in the NFPTR tem- 
plate. The data buffer is in the BTA for CRU-type devices (swapping permitted); it is in the request- 
ing task for TILINE devices (swapping not permitted). The map file that defines the segments for 
the DSR applies only while the DSR is executing. The system performs mapping. You should be 
concerned with mapping only if the DSR must map buffers in or out. 


> 0000 


> XXXX 


> cooo 


> F800 



2279422 


Figure 5-8. Memory Map for DSR Execution 
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5.4.2 DSR Entry Points 

The DNOS operating system can enter the DSR through one of the following entry points; 

• Hardware interrupt — Branches to the routine that processes interrupts from the device 

• System interrupt — Branches to the routine that processes reentry requests 

• Power up — Branches to the routine that initializes the device 

• Request abort — Branches to the routine that forces error termination of the current I/O 
request 

• Request time-out — Branches to the routine that processes a device time-out 

• I/O Request Processor — Branches to the routine that processes priority requests 

• Priority Schedule Interrupt — Branches to routine that processes priority reentry 
requests. 

The I/O subsystem requires that branch instructions for these entry points be placed at the begin- 
ning of the DSR (relative address 0) in a specific sequence. The first code of the DSR must contain 
the branch instructions for the entry points, as given in Table 5-1 . 


Table 5-1. DSR/TSR Entry Points 


Address 

Code 

Meaning 

>0000 

B ©HINT 

Hardware interrupt 

>0004 

B ©SINT 

System Interrupt (delayed reenter me) 

>0008 

B ©PWRUP 

Power up Initialization 

>000C 

B ©ABORT 

I/O abort 

>0010 

B ©TIMOUT 

Time-out 


Since these entry points are required to be at absolute locations, no data or subroutine code can 
precede these instructions. 

When a hardware interrupt occurs, the interrupt decoder executes a Branch and Link Workspace 
Pointer (BLWP) instruction in order to pass control to the DSR. The interrupt mask is set to the 
interrupt level of the device minus one to prevent another device interrupt. If a device interrupt 
enters the DSR, it destroys the current context saved in the DSR registers (R13, R14, and R15). 
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5.4.2.1 Hardware Interrupt Entry Point. The first branch instruction transfers to the routine that 
processes the hardware interrupts. This routine is the iSR. Figure 5-9 shows the functions of the 
ISR, which are to initiaiize the time-out counter, decode the interrupt, reset and process the inter- 
rupt, and return to the interrupted program. 

The time-out counter is initiaiized by moving the vaiue in the fieid PDTTM1 to the field PDTTM2. 
You can select the time-out option during system generation. The counter should be initialized in 
any case. 


Hardware Interrupt 



Input Output Unsolicited Error Timing Status 


• •• 

Interrupt Processors 



2279423 

Figure 5-9. Hardware Interrupt Processing 
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Each type of device can have several types of interrupts. Each type of interrupt is processed differ- 
ently. Figure 5-9 shows six types, although all types do not apply to every device. The types are as 
follows: 


• Input 

• Output 

• Unsolicited 

• Error 

• Timing 

• Status 

An input interrupt occurs when the device has data to be transferred to the system. This type of 
interrupt occurs after a read operation has been requested and prior to completion of the 
operation. 

An output interrupt occurs when a device is ready to receive data from the system. This type of 
operation occurs after a Write operation has been requested and prior to completion of the 
operation. 

An unsolicited interrupt occurs when the device requires service (for example, has data to be 
transferred to the system) other than during the servicing of an I/O request. 

An error interrupt occurs when the device has error data to be transferred to the system. This type 
of interrupt can occur during any operation. 

A timing interrupt occurs when the device has a timing signal required by the system. 

A status interrupt occurs when the device has status information to transfer to the system. 

The ISR must include an interrupt decoder to identify each type of interrupt that applies to the 
device and to transfer control to the interrupt processor for the proper type. 
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For keyboard devices that use the KSB as the workspace for the input ISR, three supportive rou- 
tines are available to the DSR: lOFCDT, PUTEBF, and PUTCBF. Subsequent paragraphs describe 
these routines. The following example outlines a typical input interrupt processor: 

• Move a character from the device into R10. 

• Check for input errors and process accordingly. 

• Reset the input interrupt. 

* 

* Check for bidding a task from a DSR 

LAB010 BL aiOFCDT 
BYTE >1B,>0D 
BYTE >00, >00 

DATA <speciaL-processing-done address> 

Process the character 

* 

* If the character is an event character 

* 

BL aPUTEBF 

DATA <buffer-fuLl address> 

JMP <cLean-up address> 

* 

★ Else buffer the data character 

* 

BL aPUTCBF 

DATA <buffer-full address> 

Do necessary clean up. 

RTWP 

5.4.2.2 Delayed Reentry Point. The second branch instruction transfers control to the routine 
that services requested system interrupts. It is called the RE-ENTER-ME routine. The branch 
instruction transfers control to this routine when the system receives an interrupt approximately 
50 milliseconds after the DSR sets bit DSFREN in the PDT. The I/O subsystem resets the bit on 
entry to the DSR. The DSR writer can use this feature as a timer for long delays during I/O or as a 
signaling method between the ISR and the DSR. 

5.4.2.3 Power-Up Initialization Entry Point. The third branch instruction transfers to the routine 
that initializes the device upon power-up or power restoration. This routine must Initialize the 
device interface to the proper state. 


2270510-9701 


5-19 



Writing a DSR 


5A.2A Abort Entry Point. The fourth branch instruction transfers to the routine that aborts a 
request. When a task is aborted, all I/O requests on all LUNOs must be aborted. The 
I/O subsystem attempts to find all of the requests and places a code (> 10) in the error byte of each 
request. The I/O subsystem then notifies the DSR of an aborted request by entering the DSR at the 
abort entry. This routine must clean up the processing of the request and return it to the I/O sub- 
system. 

5A.2.5 Time-Out Entry Point. The fifth branch Instruction transfers to the time-out routine. The 
associated interrupt occurs when the device does not respond within a time limit. This function is 
enabled by specifying a time-out period when the system is generated. The I/O subsystem initial- 
izes the time-out count on initial request entry, and the hardware interrupt entry must reset it on 
each entry. The time-out routine must terminate the request. 

5.4.2.6 Initial Request Entry Point. The sixth branch instruction is the request entry point. The 
DSR is entered at this point when the I/O subsystem has a request for the device and the PDT Is 
not busy. Before entering the DSR, the I/O subsystem initializes the following locations: 

• Register R1 (location PDTPRB) and location PDTSRB contain the address of the SVC 
opcode byte in the BRB. 

• The data buffer address field of the BRB contains the address of the mapped in data 
buffer (IRBDBA) template. 

• Location PDTTM2 contains the value in location PDTTM1 and indicates that the time- 
out count has been initialized. This is done by the I/O subsystem before entering the 
DSR. 

5.4.2.7 Priority Scheduler Entry Point. The seventh branch instruction transfers to the DSR 
priority scheduler. This mechanism reenters the DSR after all interrupt processing to the system is 
complete but before the task scheduler initiates any task execution. This is the most direct reentry 
path to the DSR. Its use is intended only for high-priority interrupt processing. If you use the mech- 
anism arbitrarily, you might interfere with other devices that use this fast reenter me entry point. 

5.4.3 Body of the DSR 

The body of the DSR consists of the subopcode decoder, the subopcode processing routines, and 
the end-of-record routine (see Figure 5-7). 

The subopcode decoder normally calls DSR support routine BRSTAT to decode the subopcode. 
Routine BRSTAT also collects information for online diagnostics. 

The subopcode processing routines process the I/O requests by translating them into device oper- 
ations. The number of routines required depends on the device, but usually processing routines 
for open, write, read, and close operations are provided. The device characteristics determine 
what each routine does. The programmer writing a DSR for a device must design these routines. 

After the subopcode processing routines have performed the appropriate operations, the DSR 
must call routine ENDRCD to return the request to the calling task. On return from ENDRCD, the 
DSR performs any necessary clean up and executes an RTWP instruction to return to the I/O 
subsystem. 
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5.4.4 Bidding a Task From the DSR 

DSR support routine lOFCDT provides the capability of bidding a task by a DSR for keyboard 
devices that use the KSB as the ISR workspace. The routine bids a specified task when you enter a 
predefined sequence of characters. The first character in this sequence is referred to as the 
arming character. 

A DSR for a keyboard device that does not use the KSB as the workspace or for a device that does 
not have a keyboard can also bid a task in response to a defined input sequence. The DSR must 
perform the functions of lOFCDT or an appropriate subset of those functions. 

The task to be bid from a DSR is defined in an entry in a command definition table (CDT). The 
command definition entry (CDE) contains the LUNO assigned to the program file that contains the 
task to be bid and the ID of the task. It also contains the ASCII code of the character that is 
entered to bid the task if more than one entry defines more than one task to be bid. 

Routine lOFCDT checks for an arming character before checking the CDT of the device and bid- 
ding the task when the corresponding character has been entered. 

For devices without a keyboard, the DSR must check for an arming character, if one is required. It 
must also select the correct bid character. Bidding the task consists of placing the PDT of the 
device on a queue. First, the DSR must test the value in location PDTCHR of the PDT. When the 
value is not equal to 0, a task bid is pending and another is not allowed. 

Whether to delay bidding the task until the previously requested bid has been completed or to 
Ignore the bid request is a decision that depends on the nature of the DSR and the task being bid. 
When the value in location PDTCHR is 0, put the bid character in PDTCHR and place the PDT on 
the queue beginning at location BIDREQ in common segment NFPTR. Set the interrupt mask to 
level 2 and locate the end of the queue. Location BIDREQ contains the address of location PDTBQ 
in the first PDT on the queue. That address contains 0 or the address of location PDTBQ in the 
next PDT. Locate the end of the queue by testing for 0 In location PDTBQ of each PDT. When you 
find the end, replace the 0 with the address of location PDTBQ of the PDT being serviced and set 
location PDTBQ in that PDT to 0. Then, restore the interrupt mask to the proper value for the 
device being serviced. 

A system has 25 CDTs. The Set Device Parameters suboperation in the I/O SVC defines the CDT/ 
CDE set for a device. All video display terminal (VDT) devices have the exclamation mark (!) char- 
acter defined to bid SCI and the CONTROL X sequence defined to abort a task associated with the 
terminal. You can change these or add more by using the Add CDE to CDT suboperation in the I/O 
SVC or by using the Modify Command Definition Table (MCDT) command. 

5.4.5 Multiplexing Hidden Request Queue 

For a DSR that must multiplex its input and output, a queue anchor (PDTHQR) Is Included In the 
PDT. When a DSR needs to receive a second request, it must appear to the I/O subsystem to be not 
busy. The DSR achieves this by mapping out the current request and clearing PDTSRB. It must 
then keep the first request available by queuing it to the first hidden request queue, PDTHRQ, 
using the link word BROBRO in the BRB. (See template .ATABLE.BRO to find link word BROBRO.) 
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In this way, the I/O subsystem can find a request being aborted and fiag the error byte with a 
hexadecimai 10. During an abort, the DSR is entered at the abort entry and must examine 
PDTHRQ and abort the requests marked with an error code of >10. When a request is removed 
from the hidden request queue, PDTSRB must be set to the request address to indicate that the 
device is busy. 

If you design a DSR to multiplex two or more requests at the same time, you must be careful about 
its accessing a buffer. Only the buffer for the request given to the DSR is mapped into the DSR 
address space. The mapping information for the other request remains with the request. There- 
fore, the subroutine lOMPOT must be called to map out a request buffer before inserting the 
request on the queue anchor PDTHRQ. R1 must point to the SVC and error code byte of the BRB. 
To map the request buffer into the DSR address space, the subroutine lOMPIN must be called. R1 
must point to the word of the BRB that contains the SVC code and error byte. Neither of these sub- 
routines modifies PDTSRB. 


5.5 DSR SUPPORT ROUTINES 

DNOS provides a set of support routines that a DSR can call to perform certain functions. In the 
following descriptions of these routines, the module pathnames begin with the synonym VOL. 
Assign the value < volume>.S$0SLINK (in which volume is the volume name of the system data 
disk) to synonym VOL prior to accessing these modules. 

5.5.1 Branch T able Processor Routine 

The DSR calls the branch table processor (BRSTAT) to decode the subopcode in the BRB and 
transfer control to the subopcode processing routine in the DSR. BRSTAT also collects informa- 
tion for online diagnostics. 

Defined In Module 

VOLIOMGR.OBJECT.IONRCD 

Entry 

WS — PDT 

R1 — Pointer to the BRB at the SVC opcode byte 
R4 — Pointer to the PDT at PDTPDT 
RIO — Pointer to statistics table 

Calling Sequence 

BL @ BRSTAT 

DATA max # of processors 

DATA error return address 

DATA processor address for subopcode 0 

DATA processor address for subopcode 1 


DATA processor address for subopcode n 
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Statistics Tabie 

BYTE offset into PDT for subopcode 0 
BYTE offset into PDT for subopcode 1 
BYTE offset into PDT for subopcode 2 


BYTE offset into PDT for subopcode n 

Exit 

RO — Modified 
R10 — Modified 

The online diagnostics require counts of physical I/O operations. These counts are maintained in 
the following PDT offsets: 

PDTRC Offset to Read operation count 
PDTWC Offset to Write operation count 
PDTMC Offset to miscellaneous operation count 

Routine BRSTAT uses a statistics table to associate the appropriate offset with each subopcode. 
Build the table in the DSR using the offsets in the preceding list. Use the miscellaneous operation 
offset (PDTMC) for a subopcode that performs a physical device operation other than a Read or 
Write. Enter 0 in the table for any subopcode that does not perform a physical device operation. 

The statistics table contains an entry (either an offset or 0) for each subopcode. Routine BRSTAT 
uses register R10 as a pointer to the statistics table. When either R10 or the byte in the statistics 
table corresponding to the subopcode contains 0, no statistics information is logged. 

Routine BRSTAT increments the offset count corresponding to the subopcode in the statistics 
table. If the count overflows, routine BRSTAT places > FF in location PDTERR. DNOS monitors 
PDTERR and outputs the statistics when PDTERR contains > FF. After incrementing the count, 
BRSTAT uses the subopcode to obtain the subopcode processor address from the list shown in 
the calling sequence and returns to the DSR at the address of the subopcode processor. 
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5.5.2 End-of-Record Processor Routine 

The DSR calls the end-of-record processor (ERST AT or ENDRCD) to return the BRB to the I/O sub- 
system upon completion of the request. ERST AT also collects Information for online diagnostics. 

Defined in Moduie 

VOLiOMGR.OBJECT.iONRCD 


Entry 

WS — PDT 

R4 — Pointer to the PDT at PDTPDT 
R10 — Pointer to the statistics table 
PDTSRB —Pointer to the BRB 


Caiiing Sequence 

BL @ERSTAT or ENDRCD 

Exit 

R8 — modified 
R9 — modified 
R10 — modified 

Routine ERSTAT uses R10 as a pointer to the statistics table. This is the same tabie used by 
BRSTAT. If register R10 contains a 0 (as when ENDRCD is calied) or if the byte in the statistics 
table corresponding to the subopcode contains a 0, no statistics information is logged. 

Routine ERSTAT gets the address of the BRB from the PDT, PDTSRB. It then masks interrupts to 
level 2, queues the processed request to the PDT, queues the PDT to the end-of-record list, and 
restores the interrupt ievel. 

5.5.3 Bid Task Routine 

The bid task routine (iOFCDT) bids a task from a DSR when a predefined pair of characters is 
entered at a keyboard device. System DSRs use this routine to impiement the hard break key 
sequence (refer to Appendix A to see what keys this involves for the terminal you are using) and 
sequences beginning with the arming key (biank orange key). The supported sequences for the 
911 VDT are as foilows: 


Blank orange, blank orange 
Blank orange, RETURN 
Blank orange, CONTROL X 
Blank orange, (!) 


Halt current output, resume current output 
Abort current output 
Terminate current task 
Bid SCI 


For the supported sequences, the arming character RESET is the biank orange key on the 911 
VDT. You can specify the arming character in sequences required for your DSR. Routine IOFCDT 
requires that you specify a character for the function that aborts the current output. The routine 
first checks for an abort character. If the abort character is not found, the routine checks for a bid 
character defined for the device. You can define CDT entries to specify bidding additional tasks 
when other characters are entered. 
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An entry in the CDT defines the task to be bid from a DSR. The entry contains the LUNO assigned 
to the program fiie that contains the task to be bid and the ID of the task. It also contains the ASCII 
code of the character that bids the task. If the hard break key is allowed for this device, the CDT 
must contain an entry for the lOBREAK task (installed ID > 16 on the utility program file). The sys- 
tem requires a set of entries in a CDT for each device that can bid a task. 

Defined in Moduie 

VOUOMGR.OBJECT.iOKB 

Entry 

WS — KSB 

RIO — Keyboard character (leftmost byte) 

Caiiing Sequence 
BL @IOFCDT 

BYTE ASCII code of arming character 
BYTE ASCII code of abort output character 
DATA reserved 
DATA alternate exit address 

Exit 

R6 — - Modified 
R9 — Modified 
RIO — Modified 

5.5.4 Queue Event Character or Queue Character Routine 

The queue event character (PUTEBF) and the queue character (PUTCBF) routines store a character 
in the buffer to which the registers in the KSB point. If the queue is full, the character is not stored 
and the buffer full exit is taken. 

Defined in Moduie 

VOL.iOMGR.OBJECT.iOKB 


Entry 

WS — KSB 

R1 — Count of characters in queue 

R2 — Input queue pointer 

R4 — Queue end pointer 

RIO — Keyboard character (leftmost byte) 

Calling Sequence 

BL ©PUTEBF or PUTCBF 
DATA buffer full exit address 
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5.5.5 Get Queued Character Routine 

The get queued character (GETC) routine removes a character from the character queue to which 
the registers in the KSB point and makes it avaiiable to the caiiing routine. 

Defined in Moduie 

VOLiOMGR.OBJECT.iOKB 


Entry 

WS — PDT 

R4 — Pointer to the PDT at PDTPDT 
Caiiing Sequence 
BL @GETC 

DATA buffer empty exit address 
DATA event character exit address 


Exit 


RO — Modified 

R6 — Buffer empty exit address 

R9 — Queued character (ieftmost byte) 

If the queue is empty, the buffer empty exit address is placed Into register R6 and an RTWP is exe- 
cuted. Otherwise, a character is removed from the queue. If the character is less than >80, return 
is made to the calling routine at the instruction following the calling sequence. 

If the character is >9B, it is discarded and the next character is removed. If the character is in the 
range of > 80 through > 86 or > 96 through > 9F and the LUNG is not opened to accept event char- 
acters, the character is discarded and the next character is removed. Otherwise, the event flag is 
set in the system flags byte of the request and return is made via the event character address. 
When the request is a resource-independent call, the character is reinserted at the beginning of 
the character queue for future processing by a get event character routine. 

5.5.6 Get Event Character 

The get event character (iOGEC) routine removes an event character from the character queue to 
which the registers in the KSB point. If the buffer does not contain any event characters, no action 
is taken. 

Defined in Moduie 

VOLiOMGR.OBJECT.iOKB 

Entry 

WS — PDT 

R1 — Pointer to the BRB at the SVC opcode byte 
R4 — Pointer to the PDT at PDTPDT 
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Calling Sequence 
BL @IOGEC 

Exit 

RO — Modified 
R9 — Modified 
R10 — Modified 

The call to lOGEC should be added to subopcode processor 5. Routine lOGEC checks for the reply 
flag and extended request flag in the request call block. It then attempts to remove a character 
from the character queue to which the registers in the KSB point. If the character is in the range 
> 80 through > 86 or > 96 through > 9F and not > 9B, it is removed from the queue and replaced by 
>9B. The character is placed in the event character byte of the request call block and the event 
flag is set in the system flags byte. 

5.5.7 Character Check Routines 

The seven-bit character check routine (ASCCHK) provides a means of checking for specific seven- 
bit characters. Likewise, the eight-bit character check routine (ASCCK2) provides a means of 
checking for specific eight-bit characters. Both routines transfer control to the corresponding rou- 
tine when a specified character is found. A label can precede a call to ASCCHK. 

Defined In Module 

VOLIOMGR.OBJECT.IOKB 


Entry 

WS — PDT 

R9 — Character (msb) 

Calling Sequence 

BL ©ASCCHK or ASCCK2 
BYTE char, label - $ - 1/2 
BYTEchar,label-$-1/2 
BYTE char,label-$- 1/2 
BYTE char,label-$- 1/2 


BYTE 0,0 

Exit 

RIO — Modified 
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5.5.8 Map Out Current Buffer Routine 

The map out current buffer (lOMPOT) routine is used to retain the necessary information required 
to map a buffer. This routine aiiows a device to act upon more than one request at a time. The 
mapping information is stored in the request caii biock. 

Defined in Moduie 

VOLiOMGR.OBJECT.iOBMGT 


Entry 

WS — PDT 

R1 — Pointer to the BRB at the SVC opcode byte 
R4 — Pointer to the PDT at PDTPDT 

Caiiing Sequence 

BL @iOMPOT 


Exit 


RO — Modified 

5.5.9 Get Buffer 

The get buffer routine (iOGUB) obtains a buffer from the BTA (an exampie is a buffer for the PDT 
extension). You can access this buffer by using iong-distance instructions. This routine is part of 
the root and does not require an inciude statement when iinking. 

Entry 

WS — PDT 
R1 — Buffer size 

R10 — Pointer to a five-word temporary area 

Caiiing Sequence 

REF iOGUB 
BL @iOGUB 

Exit 

R2 — BEET® 
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5.5.10 Map In Buffer 

The map in buffer (lOMPIN) routine is used to map a buffer in if it has been mapped out with the 
map out buffer routine. 

Defined in Module 

VOLIOMGR.OBJECT.IOBMGT 


Entry 

WS — PDT 

R1 — Pointer to the BRB at the SVC opcode byte 
R4 — Pointer to the PDT at PDTPDT 

Calling Sequence 

BL @iOMPiN 


Exit 


RO — Modified 

5.5.11 Get 20-Bit TILINE Address 

The get 20-bit TiLINE address (GTADDR) routine is used with TiLiNE devices to get a 21-bit physi- 
cai byte address. The vaiue is stored in the PDT extension defined by the DPD at DPDTiL > 10 to 
DPDTIL>13. 

Defined In Module 

VOLIOMGR.OBJECT.IOTILN 

Entry 

WS — PDT 

R1 — Pointer to the BRB at the SVC opcode byte 
Calling Sequence 

BL ©GTADDR 

Exit 

R9 — Modified 
RIO — Modified 
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5.5.12 Transfer PDT Information to Task Memory 

The transfer PDT information to task memory (XFERM) routine moves data in the PDT extension 
defined by the DPD at DPDWTK for the number of bytes specified. 

Defined in Moduie 

VOL 10 MG R. OBJ EC T. iO TiLN 

Entry 

WS — PDT 

R1 — Pointer to the BRB at the SVC opcode byte 
R4 — Pointer to the PDT at PDTPDT 
R6 — Count of characters to move 

Caiiing Sequence 

BL @XFERM 

Exit 

R6 — Modified 
R9 — Modified 
RIO — Modified 

5.5.13 Report TILINE Error 

The report TILINE error (TILERR) routine stores 16 bytes of TILINE information for the system log. 
If a previous error has been reported, the current error information is not stored. 

Defined in Moduie 

VOLiOMGR.OBJECT.iOTiLN 

Entry 

WS — PDT 

R4 — Pointer to the PDT at PDTPDT 
R10 — Error code (msb) 

R12 — TPCS address 

Caiiing Sequence 

BL ©TILERR 

Exit 

R8 — Modified 
R9 — Modified 
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5.6 ASYNCHRONOUS DSR STRUCTURE 

As the structure common to all DSRs has already been discussed, this paragraph describes the 
DSR structure specific only to asynchronous device support. In this paragraph, the term DSR 
refers to an asynchronous DSR. Table 5-2 shows the device and controlier combinations that are 
supported by asynchronous DSRs. 


Table 5-2. Asynchronous Device Support 





Devices 


Controllers 

931 

940 

Business 

System 

Terminal 

810 840 85X 

CI401 

Y 

Y 

Y 


CI421 



Y 

Y Y 

CI422 



Y 

Y Y 

/10A^ 

Y 

Y 

Y 

Y Y 

CI402 

Y 

Y 

Y 

Y Y 

CI403 

Y 

Y 

Y 

Y Y 

CI404 

Y 

Y® 

Y® 

Y® Y® 

AUX1 of 

931 3 




Y Y 

AUX1 of 

Business 

System 

Terminal® 




Y Y Y 

AUX1 of 

940® 




Y Y Y 

Notes: 





^ /10A refers to the TMS9902 communications port on the 990/10A processor printed circuit board. 

® These devices are connected to the CI404 via the fiber optics to EIA RS-232C converter module. 

® AUX1 refers to the auxiliary port found on the 931, 940, and Business System terminals. 
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The asynchronous DSR design separates controller and device support into different software 
modules. Figure 5-10 displays a block diagram of the DSR structure. The DSR consists of three 
basic modules. The hardware controller service routine (HSR) module provides the controller sup- 
port. The terminal service routine (TSR) module provides device support. The interrupt service rou- 
tine (ISR) module has Interrupt and high priority processing responsibility. The following list 
describes the basic functions of the DSR components. 

• TSR module 

— Contains all DSR entry points (hardware interrupt, system interrupt, power up, I/O 
abort, time-out, priority scheduler) 

— Provides request and completion reporting interface to DNOS 

— Runs in PDT workspace 

— Provides software interface to device 

— Contains device dependent logic 

• ISR module 

— Contains hardware Interrupt processing routine of the DSR 
— Provides interface to HSR for interrupt processing 
— Provides high priority receive character processing 
— Runs In DSR Interrupt workspace (not the PDT workspace) 

• HSR module 

— Provides generic (subroutine) software interface to the controller hardware 
— Contains all controller dependent logic 
— Contains ail direct access to controller 
— Presents a buffered controller Interface to other DSR modules 
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5.6.1 Asynchronous DSR Design Overview 

Figure 5-11 shows a detailed DSR flow diagram. This figure shows data flow paths as well as the 
DSR logic flow. Refer to Figure 5-11 during the following discussion of the DSR logic and data 
flow. The TSR module contains all DSR entry points. It accepts requests from, and reports comple- 
tions to, the I/O subsystem of DNOS. The primary function of the TSR is to provide a software 
interface to the peripheral device. The actual functions vary considerably based on the type of 
device. 

The TSR performs initial processing for all requests. The TSR calls the HSR for the output of data. 
The HSR stores output data in a transmit FIFO until the data can be transmitted on the communi- 
cations line. 


NOTE 

Buffered controllers such as the CI403 contain a hardware transmit 
FIFO. For non-buffered controllers such as the CI422, the HSR 
maintains a software transmit FIFO. 


The HSR cannot accept data when the transmit FIFO is filled with data waiting to be transmitted. 
In this event, the TSR requests to be notified (by the ISR) when the HSR can accept more data. The 
HSR notifies the ISR when it can accept more transmit data, and the ISR schedules the TSR using 
the DSR priority schedule or reenter-me mechanism. The TSR can then resume transferring output 
data to the HSR. Figure 5-11 shows the logic paths followed in this process. Under normal condi- 
tions, the TSR reports completion of the output request before the HSR has actually transmitted 
all the data on the communications line. 

Read requests, in most cases, require the cooperation of the TSR and ISR modules. The TSR 
attempts to satisfy the read by moving received data from the receive character queue to the 
user’s read data buffer. When the TSR satisfies the read, it reports completion to the user task via 
the operating system I/O support routines. When there are not enough characters in the receive 
queue to satisfy the read, the TSR must wait. To do this, the TSR requests notification from the 
ISR when more data is stored in the receive character queue. The TSR then releases control. When 
the ISR stores data in the receive character queue, it schedules the TSR for execution. Other I/O 
service requests are processed by the TSR with the aid of the ISR when required. 

The ISR module contains some functions that you can consider device support and some that you 
can consider controller support. The ISR module contains the hardware interrupt routine to which 
the TSR hardware interrupt entry points. The ISR module uses an interrupt workspace different 
than the physical device table (PDT) workspace. The ISR module runs with controller interrupts 
masked. The ISR calls the HSR to decode the controller interrupt. 

For the most part, ISR processing is independent of request processing by the DSR. Received data 
is stored in the receive character queue even when no read request is active at the DSR. Error 
recovery action must be taken when the receive character queue becomes full. The ISR processes 
events requiring immediate attention. It also schedules the TSR module to start or resume 
processing. 
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The HSR provides access to the controller hardware. The HSR provides a generic Interface to the 
controller. This allows other DSR modules to be written that are Independent of the asynchronous 
controller type. HSR functions Include controller and communications channel Initialization, 
transmission of data, timer services, monitoring of modem signals, and controller Interrupt decod- 
ing. The HSR does not support the concept of a read request. The HSR decodes the controller 
Interrupt and reports the cause for the Interrupt to the ISR. If the cause of the Interrupt was a 
received data character, the data character Is also passed back to the ISR. The HSR does not 
store the receive data. 

5.6.2 Terminal Service Routine (TSR) 

The TSR module Is the Interface to the I/O subsystem of DNOS. Like a DSR does. It must Imple- 
ment all the following DNOS Interface functions: 

• DNOS I/O subsystem entry points 
— Hardware Interrupt 

— System interrupt (delayed reentry) 

— Power-up 
— Request abort 
— Request time-out 
— Priority scheduler 
— Request processor 

• Data structures 

— Physical device table (PDT) 

— Keyboard status block (KSB)/lnterrupt workspace 
— Asynchronous device extensions (DSALLLEX, DSALLREX) 

• I/O subsystem routines 
— BRSTAT 

— BZYCHK 
— ENDRCD 
— GETC 

— lOFCDT 

— lOFGEC 
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— lOGUB 
— PUTCBF, PUTEBF 

The following two mechanisms allow scheduling the TSR from an ISR: 

• Delayed reentry 

• Priority schedule 

5.6.3 Interrupt Service Routine (ISR) 

The interrupt service routine (ISR) contains the interrupt routine of the DSR and uses the ISR work- 
space of the DSR. 


NOTE 

Each channel of an interface supported by the asynchronous DSR 
structure must have an interrupt workspace different than the PDT 
workspace. 


The ISR interfaces with both the TSR and the HSR. The design of the TSR/ISR interface is not dic- 
tated by the asynchronous DSR design. For the most part, you can specify it to fit your needs. The 
following list provides examples of ISR functions for standard keyboard devices: 

• Bid application task 

• Suspend output 

• Abort output 

• Abort application task (hard break) 

Figure 5-12 shows the flow of control during Interrupt processing. The DSR is entered at its inter- 
rupt entry point via a BLWP instruction. The workspace upon entry is the DSR interrupt work- 
space. This is the same workspace the ISR uses. 

The ISR is responsible for controlling further interrupt decoding by the DSR. If you are using the 
HSR supplied by Texas instruments, the ISR calls the HSR subroutine HNOTIF (refer to paragraph 
5.7.9) to determine what type of controller interrupt occurred. The ISR provides return vectors for 
each interrupting condition of the controller. Figure 5-12 uses the word VECTOR to describe this 
process. The description of the HNOTIF subroutine documents the set of generic interrupt 
conditions. The HNOTIF subroutine takes the return vector associated with the current controller 
interrupt. 

The ISR code for the specific type of interrupt takes the proper action to service the interrupt. 
When complete, the ISR returns to the operating system interrupt decoder via an RTWP instruc- 
tion. The operating system decoder takes the necessary action to restore normal system 
execution. 
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Figure 5-12 shows one other path for interrupt processing. The HSR exits or returns directly to the 
operating system interrupt decoder if HNOTIF is called when no controller interrupt is pending. 
This special return exists to support certain ISRs; most user ISRs never use this path. 



228470 1 


Figure 5-12. Interrupt Processing Flow 


5.6.4 Hardware Controller Service Routine (HSR) 

The generic interface to the HSR consists of a set of subroutines with a branch and link (BL) call 
interface. A subroutine implements one or more generic functions for the specific controller in 
use. For example, the TSR makes a Set DTR subroutine call. The HSR for a CRU controller might 
Implement this as a SBO DTR CRU instruction. However, the HSR for a TILINE controller may 
implement the same subroutine by using a SOC @DTR,@OUTSIG(R12) instruction to access the 
TILINE Peripheral Control Space (TPCS) of the controller. Identical requests from the TSR/ISR 
Invoke identical functions for all controllers. Provision is made for controller hardware differ- 
ences. A “not supported” return is provided for most HSR subroutines. This return is taken when 
the requested function is not supported by the controller hardware. 

The asynchronous DSR design can support several device and controller combinations. HSR 
object modules are provided with the operating system for the controllers listed in Table 5-3. Table 
5-3 also documents the final node in the pathname for each HSR. The directory that contains the 
HSR object modules is < volume> .S$OSLINK.DEVDSR.OBJECT, where < volume> is a synonym 
that you assign. 
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Table 5-3. HSR Object Modules 


Name 

Controller Type 

DS403HSR 

CI403/CI404 

DS923HSR 

TMS 9902 and 9903 controllers (*) 

DS401HSR 

CI401 (previously COMM l/F) 

Note: 


* Includes CI402, CI422, CI421, the 990/10A 9902 port, and the 9902 interface asso- 
ciated with the internal terminal on the Business System 300 computer. 


These modules are made available for users implementing DSRs for special devices connected to 
these controllers. These HSR modules are used for DSRs following the asynchronous DSR design. 
This design must be followed for user written DSRs under the following conditions: 

• The special device is connected to a CI403 or CI404 controller 

• A standard Tl DSR is used to support any of the communication channels of the CI403 or 
CI404 

When these conditions do not occur, you have a choice of DSR designs for asynchronous device 
support. You can implement either the asynchronous DSR design or a design of your choice. 
Remember that any user design must observe all DNOS constraints. 

5.6.5 Asynchronous Data Structure Allocation 

The DIB (the PDT extension) is divided into two segments. One segment is physically contiguous 
to the PDT. This segment contains data that requires the most frequent access and must be cre- 
ated before the ALGS step of system generation is done. The segment must have the following 
pathname: 

< volume> .S$OSLINK.S$SGU$.SD.DIBXXXX 

The other segment contains data for which an Increased access time does not significantly affect 
overall performance. The second segment must be accessed using long-distance instructions. 
Other data structures included in the long-distance extension are VDT screen images for VDT 
DSRs. Refer to Figure 5-13. 
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All the data structures that are not accessed via long-distance instructions must be created 
before the completion of system generation. These data structures are available when the operat- 
ing system is loaded into memory from disk. The long-distance data structures must be allocated 
during the power-up initialization of the operating system. The TSR is responsible for allocating 
the second long distance PDT extension by using the system routine lOGUB. if you are using the 
HSR module supplied by Texas Instruments, this extension must be allocated and words PDXSMB 
and PDXSMP must be initialized with the PDT extension address before the TSR can call any of 
the HSR subroutines. The size of the extension must be at least 144 bytes for nonbuffered con- 
trollers and at least 32 bytes for buffered controllers (CI403/CI404). The user has the option of 
specifying additional space for the user-written TSR/ISR. The user can also lengthen the local PDT 
extension by reserving more memory In the DIB that is provided to the system generation program. 
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Figure 5-13. Asynchronous Data Structure Linkages 
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5.7 HSR COMMON SUBROUTINES 

The information required to interface to the HSR moduie is as foiiows: 

• Subroutine names 

• Functions provided by each subroutine 

• Subroutine caliing conventions 

This information is discussed in the foilowing paragraphs. 

The foiiowing iist describes the HSR subroutine ciasses. Each ciass contains severai subroutines. 
These subroutines provide one or more HSR functions. 

• Power-up initialization 

• Write output signal or function 

• Read input signal or function 

• Enable/disable status change notification 

• Output a character 

• Write operational parameters 

• Read operational parameters 

• Request timer interval notification 

• Controller interrupt decoding 

All HSR subroutines are called via branch and link (BL) instructions. Thus, they use the caller’s 
workspace during execution. Parameters required by the subroutines are passed to the HSR in 
workspace registers. Information is returned to the caller in one of two ways. Data Is returned to 
the caller In workspace registers. Other status information is returned by way of alternate subrou- 
tine returns. The caller specifies alternate return addresses as operands of DATA assembler direc- 
tives immediately following the BL subroutine call. The following shows an example of HSR 
alternate return addresses: 

BL @HSRSUB SUBROUTINE CALL 

DATA ALT1 FIRST ALTERNATE RETURN 

DATAALT2 SECOND ALTERNATE RETURN 

**** NORMAL RETURN (CODE) 

The caller execution resumes at one of the alternate return addresses or at the normal return 
address (the instruction following all alternate return DATA statements). The number of alternate 
returns varies for different HSR subroutines. 
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The HSR subroutines follow some general register conventions. The subroutines normally use RO 
and R10 as working registers. These two registers are also used when parameters are passed to or 
from the HSR. Exceptions are noted In some of the HSR subroutine descriptions. In most cases, 
R7 is used as a pointer to the PDT. R12 contains the TILINE or CRU base address of the controller 
or controller channel. Other register usage is documented with specific HSR subroutines. 

5.7.1 Power-Up Initialization 

This subroutine class allows the HSR to perform any Initialization required before operation 
begins. The long distance buffer must be allocated before the HSR power-up subroutine is called. 

For the CI403 and CI404, the HSR is required to ensure that the controller has successfully exe- 
cuted the self-test for each channel specified during system generation. For other controllers, the 
HSR may be required to build a software transmit FIFO in a long-distance memory buffer that is 
obtained by the operating system. 

The three subroutines that perform power-up Initialization functions are as follows: H RESET, 
HSWPWR, and HMRST. 

The HRESET subroutine performs power-up initialization that must be performed for all I/O chan- 
nels of the controller. This subroutine can be called once per channel for multiple channel con- 
trollers. However, there is only one master reset of the controller for each power-up occurrence. 

The HSWPWR subroutine performs all channel-oriented initialization. The HSR data structures for 
the channel are initialized. Controller interrupts are enabled when the normal return is taken. 

The HMRST subroutine performs the same initialization functions as the HRESET routine except 
that a master reset of the controller is unconditionally performed. This subroutine is provided so 
that diagnostic software can force a controller master reset fortesting purposes. 

The TSR normally makes two calls to the HSR for power-up initialization. The HRESET subroutine 
is called first, followed by the HSWPWR subroutine. These two subroutines are called for each 
channel of the controller. The calling conventions are identical for each of the HSR power-up sub- 
routines. If HPOWER is considered a synonym for any of the three power-up subroutine names, 
then the calling conventions for all HSR power-up subroutines are as follows: 

Calling convention: 

©HPOWER 

XXXX POWER UP FAILURE RETURN VECTOR 

NORMAL RETURN (CODE) 


BL 

DATA 
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5.7.2 Write Output Signal or Function 

The subroutine names for setting output signais or functions to 1 (iogic true) are of the form 
HSTxxx, where xxx specifies a signai or function. The subroutine names for resetting output sig- 
nais or functions to 0 (iogic false) are of the form HRTxxx, where xxx specifies a signal or function. 
The following list describes the output signals supported by HSRs: 


Subroutine 


Signai 


HSTAL, HRTAL 
HSTDTR, HRTDTR 
HSTRTS, HRTRTS 
HSTSRS, HRTSRS 
HSTSRT, HRTSRT 


AL — Analog Loopback (Signal) 

DTR — Data Terminal Ready (Signal) 

RTS — Request to Send (Signal) 

DSRS — Data Signal Rate Select (Signal) 
SRTS — Secondary Request to Send 
(or Reverse Channel Signal) 


The following list describes the output functions supported by HSRs. 


Subroutine 


Function 


HSTBIUHRTBIL 
HSTCR, HRTCR 
HSTCTH, HRTCTH 
HSTRS, HRTRS 
HSTTB, HRTTB 
HSTUIUHRTUIL 


BIL— Board Internal Loopback (Function) 

CR — Channel Reset (Function) 

CTH — Channel Transmitter Halt (Function) 
RS — Receiver Squelch (Function) 

TB — Set Transmit Break condition (Function) 
UIL — DART Internal Loopback (Function) 


The calling conventions for the HSTxxx and HRTxxx subroutines are identical. The following call- 
ing convention uses the HSTxxx name as an example: 

Calling convention: 

BL ©HSTxxx WHERExxxISDTR, RTS, ETC. 

DATA VVVV SIGNAL NOT SUPPORTED RETURN VECTOR 

NORMAL EXIT (CODE) 

The following paragraphs describe each of the functions in detail. 

5.7.2.1 HSTBIL Subroutine. The Set Board Internal Loopback subroutine (HSTBIL) provides for 
setting a more general (controller or board) internal loopback mode than the UART internal loop- 
back mode. None of the current asynchronous controllers support this second level of loopback. 

5.7.2.2 HSTCR Subroutine. The Set Channel Reset subroutine (HSTCR) performs a hardware 
reset of the channel. This does not disturb any other communication channels. The channel inter- 
rupts are not enabled by this subroutine. The HRTCR subroutine enables interrupts and allows 
normal operation. The following example shows a typical sequence for TSR use of these 
subroutines: 

1 . TSR issues an HSTCR call to quiet HSR activity on the channel. 

2. TSR issues an HSWPWR call to initialize the HSR data structures and status. 
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3. TSR initializes its channel data structures and status. 

4. TSR then issues an HRTCR call to begin normal operation. 

5.7.2.3 HSTCTH Subroutine. The Set Channel Transmitter Halt subroutine (HSTCTH) temporar- 
ily suspends output of data to the communications line. Any data in the transmit FIFO is not trans- 
mitted. The HRTCTH subroutine resumes transmission of data in the transmit FIFO. 

5.7.2.4 HSTRS Subroutine. The Set Receiver Squelch subroutine (HSTRS) enables half-duplex 
operation. The receiver squelch function disables reception of data during transmission. The 
HRTRS subroutine turns the receiver squelch off and allows full-duplex operation. 

5.7.2.5 HSTTB Subroutine. The Set Transmit Break subroutine (HSTTB) initiates the 
transmission of a break sequence (spacing/logic 0). This continues until stopped with the HRTTB 
subroutine. 


5.7.2.6 HSTUiL Subroutine. The Set UART internal Loopback subroutine (HSTUIL) places the 
UART (communications chip) for the channel in loopback mode, in general, this causes the UART 
to return all transmitted data as received data on the same channel. Refer to UART documentation 
for more detailed information. The HRTUIL subroutine changes the UART from UART internal 
loopback to normal mode. 

5.7.3 Read input Signai or Function 

This subroutine class allows reading controller input signals and HSR function states. The HSR 
subroutine name is of the form HRDxxx, where xxx Identifies a signal or function. The following 
list describes the input signals or function states that can be read: 


Subroutine 


Signai/Function 


HRDBIL 

HRDCR 

HRDCTH 

HRDCTS 

HRDDCD 

HRDDSR 

HRDRI 

HRDSCT 

HRDSDC 

HRDSSS 

HRDTB 

HRDUIL 


BIL — Board Internal Loopback (Signal) 

CR — Channel Reset (Function) 

CTH — Channel Transmission Halted (Function) 
CTS — Clear to Send (Signal) 

DCD — Data Carrier Detect (Signal) 

DSR — Data Set Ready (Signal) 

Rl — Ring Indicator (Signal) 

SCTS -- Secondary Clear to Send (Signal) 

SDCD — Secondary Data Carrier Detect 
(or Speed indication Signai) 

SSS — Split Speed Supported (Function) 

TB — Transmit Break (Function) 

UIL — UART Internal Loopback (Signal) 


Calling Convention: 


BL 

@ HRDxxx 

DATA 

}} 

DATA 

YYYY 

DATA 

ZZZZ 


WH ERE xxx IS DSR, CTS, ETC. 

SIGNAL NOT SUPPORTED RETURN VECTOR 
CONTROLLER FAILURE RETURN VECTOR 
SIGNAL FALSE RETURN VECTOR 
SIGNAL TRUE RETURN (CODE) 
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5.7.4 Enable/Disable Status Change Notification 

This subroutine class provides a mechanism for the ISR (and therefore, indirectly the TSR) to 
receive status change notification from the HSR. There are subroutines to enable notification and 
to disable notification. Once enabled, most of the signals or functions that are supported remain 
enabled until explicitly disabled. 

The Transmit Shift Register Empty (TSRE) function is an exception to this rule, if the HSR makes a 
TSRE status notification, it automatically disables further notification for this same condition. 
The TSRE function must be enabled with another HDSTSR call to the HSR if subsequent notifica- 
tion is desired. Refer to the HSR interrupt decoder description for more details about the method 
of notification. 


Notification is made when the signal changes from 0 to 1 or from 1 to 0 for the first five signals. 
Some controllers notify only on the ring signal changing from 0 to 1. The TSRE notification is 
made only when the condition occurs. 


The subroutine names for enabling status change notification are of the form HESxxx, where xxx 
specifies a signal or function. The subroutine names for disabling status change notification are 
of the form HDSxxx, where xxx specifies a signal or function. The following list describes the noti- 
fication conditions that the HSR supports: 


Subroutine Status Change Notification 


HESCTS, HDSCTS 
HESDCD, HDSDCD 
HESDSR, HDSDSR 
HESRI, HDSRI 
HESSCT, HDSSCT 
HESSDC, HDSSDC 
HESTSR, HDSTSR 


GTS — Clear to Send 

DCD — Data Carrier Detect 

DSR — Data Set Ready 

Rl — Ring Indicator 

SCTS — Secondary Clear to Send 

SDCD — Secondary Data Carrier Detect 

TSRE — Transmit Shift Register Empty 


The calling conventions for the HESxxx and HDSxxx subroutines are identical. The following call- 
ing convention uses the HESxxx name as an example: 

Calling Convention: 

BL ©HESxxx WHERE xxx IS DSR, Rl, ETC. 

DATA VVVV NOT SUPPORTED RETURN VECTOR 

NORMAL RETURN (CODE) 
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5.7.5 Output a Character 

This HSR subroutine accepts characters to be output on the communications channel. The 
subroutine provides a character interface to the output channel (that is, only one character is 
passed to the HSR for each HOUTPx subroutine call). In all cases, the output data is stored in a 
transmit FIFO before transmission on the communications line. For buffered controllers, the FIFO 
is on the hardware controller. For non-buffered controllers, the FIFO is a software data structure 
that the HSR manages. An alternate (character not output) return from the HOUTPx routine is 
taken if the FIFO becomes full. The caller is responsible for saving the data character. The HSR 
notifies the ISR when the transmit FIFO is empty. This notification takes place as a transmit 
interrupt exit from the HSR interrupt decoder subroutine. This notification causes the output data 
to flow to the HSR again. Refer to the HSR interrupt decoder subroutine description for more 
details. 

The output character subroutines are HOUTP4 and HOUTP7. The only difference in these two sub- 
routines is that workspace register R4 contains the PDT pointer for the HOUTP4 subroutine and 
R7 contains the PDT pointer for the HOUTP7 subroutine. 

Calling Convention: 

BL ©HOUTPx 

DATA XXXX 


where: 

R7 or R4 contains the pointer to the PDT. 

R5 is the output character, left byte. 

Volatile Registers: 

RO and R5 

R5 preserved for character not output 

5.7.6 Write Operational Parameters 

The following list describes the operational parameters that the HSRs support. 

• Baud rate selection — The transmit baud rate and the receive baud rate are specified in 
the most significant bit (MSB) and least significant bit (LSB) of RO, respectively. The 
MSB and LSB must be identical for controllers not supporting dual speeds. 

• Data format: 

— Parity selection: even, odd, mark, space, or none 
— Character length selection: 5, 6, 7, or 8 bit data 
— Stop bit selection: 1 , 1 .5, 2 stop bits 


x = 4IFR4ISPDT POINTER 
x = 7IFR7ISPDT POINTER 
CHARACTER NOT OUTPUT — RETURN VECTOR 
NORMAL (CHARACTER OUTPUT) RETURN 
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The write parameters subroutines are Set Channel Speed (Baud Rate) and Set Data Character 
Format. The calling conventions for these two subroutines are very similar. The only difference is 
the parameter information passed in RO. 

5.7.6.1 Set Channel Speed (Baud Rate). This subroutine specifies the transmit and receive 
rates for the channel. The transmit and receive rates may differ only when dual rates are 
supported. 

Calling Convention: 

BL ©HSPSPD SET CHANNEL SPEED 

DATA VVVV PARAMETER NOT SUPPORTED RETURN VECTOR 

NORMAL RETURN (CODE) 


where: 

RO MSB contains the transmit rate code; 
LSB contains the receive rate code. 
(Refer to Table 5-4.) 


Table 5-4. HSR Baud Rate Codes 


Speed Code Baud Rate 


00 

01 

02 

03 

04 

05 

06 

07 

08 

09 
OA 
OB 
OC 
OD 
OE 
OF 

10 

11 through FF 


50 baud 
75 baud 
110 baud 
134.5 baud 
150 baud 
200 baud 
300 baud 
600 baud 

1.200 baud 

1 .800 baud 
2,400 baud 

3.600 baud 

4.800 baud 

7.200 baud 

9.600 baud 
14,400 baud 
19,200 baud 

Reserved 
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5.7.6.2 Set Data Character Format. This subroutine sets the character iength, parity seiection, 
and the number of stop bits for data characters. 

Caiiing Convention: 

BL @ HSPPSL SET DATA CHARACTER FORMAT PARAMETERS 

DATA VVVV PARAMETER NOT SUPPORTED RETURN VECTOR 

NORMAL RETURN (CODE) 


where: 

RO contains the parameter information in the following format: 


Bit 

Contents 

0-1 

Reserved 

2-3 

Parity selection 

00 = odd parity 

01 = even parity 

10 = mark parity 

11 = space parity 

4 

Parity enable 

00 = not enabled 

01 = enabled 

5-7 

Reserved 

8-9 

Number of stop bits 

00 = 1 stop bit 

01 = 1.5 stop bits 

10 = reserved 

11 = 2 stop bits 

10-11 

Data character length 

00 = 5 bit character 

01 = 6 bit character 

10 = 7 bit character 

11 = 8 bit character 

12-15 

Reserved 


5.7.7 Read Operational Parameters and Information 

This class of subroutines allows the following operational parameter values to be read from the 
HSR: 


Subroutine 


Operational Parameter Value 


HRPDAT 

HRPPSL 


HRPSPD 

HRPTYP 


HSR module revision level 
Data format: 

Parity selection: even, odd, mark, space, or none 

Character length selection 

Stop bit selection 

Baud rate 

Controller type ID 
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The parameter information is returned in RO of the cailer’s workspace. For the HRPSPD and 
HRPPSL subroutines, the format of the information in RO is identicai to the format in the HSPSPD 
and HSPPSL subroutines, respectiveiy. 

Caiiing Convention: 

BL @HRPxxx WHERE XXX iSSPD OR PSL 

RETURN 

The HRPDAT subroutine returns the current revision ievei of the HSR software module in RO. The 
revision level Is a hexadecimal number starting at 0 for the initial level and Incrementing by one for 
each revision. The HRPTYP subroutine returns a code right justified in RO that identifies the con- 
troller type. Table 5-5 lists controller type codes. 


Table 5-5. Controller Type Codes 


Code 

Controller 

>0001 

CI401 (previously COMM l/F) 

>0006 

Business System 300 internal 9902 port 

>0007 

990/1 OA 9902 port 

>0008 

CI402 

>0009 

CI421 9902 port 

>000A 

CI422 

>0023 

CI403 

>0024 

CI404 

>0030 

CI421 9903 port 


5.7.8 Request Time Interval Notification 

This subroutine (HTIMER) requests notification after a specified time interval. You specify the 
time interval as a multiple of 250-millisecond periods. The HSR interrupt decoder performs the 
notification by taking the timer interrupt vector return to the ISR. Refer to the discussion of the 
HSR interrupt decoder for more details. Timer notification is disabled by specifying a zero as the 
number of 250 millisecond intervals (RO = 0). There is not a “not supported” exit provided for this 
subroutine. 

Calling Convention: 

BL ©HTIMER 

where: 

RO specifies the number of 250-millisecond intervals. 
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5.7.9 Controller Interrupt Decoder 

The ISR calls this subroutine (HNOTIF) to perform controller interrupt decoding. The subroutine 
executes in the DSR interrupt workspace and with interrupts masked to the interrupt ievel of the 
controller channel. The ISR provides severai return vector addresses via DATA directives immedi- 
ately following the cail. A return vector is provided for each interrupt type possibie from the con- 
troller. If the subroutine finds no controller interrupt pending, the return is to the operating system 
interrupt decoder rather than the caller. 

Calling Convention; 


BL 

@HNOTIF 

DATA 

XXXX 

DATA 

YYYY 

DATA 

ZZZZ 

DATA 

AAAA 

DATA 

BBBB 


RECEIVE INTERRUPT VECTOR 
TRANSMIT INTERRUPT VECTOR 
SIGNAL OR FUNCTION CHANGE VECTOR 
TIMER INTERRUPT VECTOR 
ILLEGAL/INVALID INTERRUPT VECTOR 


Receive Interrupt Return: 


R10 Received character ieft byte 

Line status in right byte 

Meaning 

Reserved 

^ Break Received 

4 Framing Error 

^ Parity Error 

® Overrun Error 

^ Reserved 

Transmit Interrupt Return: 

This return is taken when the transmit FIFO empties. 
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Signal or Function Change Return: 

R10 Current signal or function states are returned in bits 0-3 and bits 8- 10. 

Bits 4-7 and 12-15 are delta flags that indicate which signals or func- 
tions changed. 


Bit Contents 


0 

DCD 

1 

Rl 

2 

DSR 

3 

CTS 

4 

Delta DCD 

5 

Delta Rl 

6 

Delta DSR 

7 

Delta CTS 

8 

SCTS 

9 

SDCD 

10 

TSRE 

11 

Reserved 

12 

Delta SCTS 

13 

Delta SDCD 

14 

Delta TSRE 

15 

Reserved 


5.8 DSR INSTALLATION 

After writing the DSR, you must assemble and link edit it. Assemble the DSR by executing the 
Execute Macro Assembler (XM A) SCI command and making the correct responses. 


After you assemble the DSR, you must link it with all of the required support subroutines. This is 
required with each release of the operating system, not with each system generation between 
releases. The following example shows a typical link control stream used to link a DSR: 


NOPAGE 

ERROR 

PROCEDURE 

DUMMY 

INCLUDE 

PHASE 

INCLUDE 

INCLUDE 

INCLUDE 

END 


DUMROOT 


<vo lume> . S $08 LI N K. S$SGU$. DUMROOT 
0 , DSRname , PROG >C000 
dsr object pathname 

<volume>.S$0SLINK.I0MGR.0BJECT.I0NRCD 
(any other support routines) 


Note: < volume> refers to the volume name of the data disk used during system generation. 
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The Execute Link Editor (XLE) SCI command executes the Link Editor. The linked output access 
name should be <volume>.S$OSLINK.S$SGU$.SD.DSRxxxxx, where xxxxx represents the spe- 
cial device name defined at system generation. Later, the system generation utiiity wiii expect the 
DSR to be found in this file. 


Special extensions to the PDT (DIBs) must be in the file <volume> 
.S$OSLINK.S$SGU$.SD.DIBxxyy, where xx is the first two characters of the special device name 
specified during system generation (ST if the device has a keyboard), and yy is the device ID gener- 
ated by the system generation utility (for example, 03 in ST03). 

If you build an asynchronous DSR that is to be linked with an HSR module that is supplied by Tl, 
you must first include the TSR module (which contains the DSR entry points). The following is an 
example of a link control stream: 


NOPAGE 

ERROR 

PROCEDURE 

DUMMY 

INCLUDE 

PHASE 

INCLUDE 

INCLUDE 

INCLUDE 

INCLUDE 

END 


DUMROOT 

<vo Lume>. S $08 LINK. S$SGU$. DUM ROOT 
0 , DSRname , PROG >C000 
tsr object pathname 

<vo Lume>. SSOSLINK. D EVDSR. OBJECT. HSRname 
<volume>. SSOSLINK. lOMGR.OBJECT. lONRCD 
(any other support routines) 


Note: < volume> refers to the volume name of the data disk used during system generation. 


5.9 DEBUGGING TECHNIQUES 

The best debugging technique Is to produce a well-documented DSR. This makes it easier to 
locate errors and makes the coding clearer to others. In addition to good documentation, 
thorough code reading with coiieagues heips reduce errors. 

Missing indexing registers are typical of the errors found through code reading. When the struc- 
ture begins with IRBxxx, R1 should be the index register. When the structure begins with PDTxxx 
or is an extension to the PDT, R4 should be the index register. 

The next step is debugging the DSR on the computer in a restricted environment. The JMP $ 
instruction can be placed at strategic points within the DSR. When the computer executes one of 
these instructions, the PC remains at that location until the JMP $ instruction is removed. This 
enables the programmer to use the computer front panel to examine DSR behavior and data used 
by the DSR. The SIE mode can be used if the value of ST is changed to xxx2. 


5.10 DSR EXAMPLE 

Figure 5-14 shows the source code listing of a DSR for a line printer. This listing shows a typical 
application of the guidelines for writing a DSR. You may adapt this DSR to nonsupported devices. 
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SDSMAC 3.5.0 82.130 16:53:03 FRIDAY, JUN 17, 1983. 


ACCESS NAMES TABLE PAGE 0001 

SOURCE ACCESS NAME= DS01.DSRLP 

OBJECT ACCESS NAME- DUMY 

LISTING ACCESS NAME= DS01.LPLST 

ERROR ACCESS NAME= 

OPTIONS^ RXREF 


MACRO LIBRARY PATHNAME^ 

LINE KEY NAME 

0002 A OSC.CONDASM.OS 

s>.S$0SLINK.C0NDASM.0S 
OUO LI DSC. MACROS. TEMPLATE 

=>.S$OS LINK. MACROS. TEMPLATE 
0141 LI DSC. MACROS. FUNC 

=>.S$OS LINK. MACROS. FUNC 

0149 B DSC. TEMPLATE. ATABLE. IRB 

=>. S$OS LINK. TEMP LATE. ATABLE. I RB 

0150 C DSC. TEMPLATE. ATABLE. PDT 

==>.S$OS LINK. TEMP LATE. ATABLE. PDT 
0157 0 DSC. TEMPLATE. ATABLE. LPD 

=>. S$OS LINK. TEMP LATE. ATABLE. LPD 

0256 E DSC. TEMPLATE. COMMON. NFERR1 

=>.S$OS LINK. TEMP LATE. COMMON. NFERR1 
E0007 F DSC. TEMPLATE. COMMON. NFEROO 

=>. S$OS LINK. TEMP LATE. COMMON. NFEROO 
E0008 G DSC. TEMPLATE. COMMON. NFER10 

=>.S$OS LINK. TEMP LATE. COMMON. NFER10 
E0009 H DSC. TEMPLATE. COMMON. NFER20 

=>.S$OS LINK. TEMP LATE, COMMON. NFER20 
E0010 I DSC. TEMPLATE. COMMON. NFER30 

=>.S$OS LINK. TEMP LATE. COMMON. NFER30 

0257 J DSC. TEMPLATE. COMMON. NFWORD 

=>. S$OS LINK. TEMP LATE. COMMON. NFWORD 
DSRLP SDSMAC 3.5.0 82.130 16:53:03 FRIDAY, JUN 17, 1983. 

DSRLP - DNOS LINE PRINTER DSR PAGE 0002 

0002 COPY OSC.CONDASM.OS 

0006 IDT ‘DSRLP* 

0016 * 

0017 * (C) COPYRIGHT, TEXAS INSTRUMENTS INCORPORATED, 1979. 

0018 * ALL RIGHTS RESERVED. PROPERTY OF TEXAS INSTRUMENTS 

0019 * INCORPORATED. RESTRICTED RIGHTS - USE, DUPLICATION 

0020 * OR DISCLOSURE IS SUBJECT TO RESTRICTIONS SET FORTH 

0021 * IN TI'S PROGRAM LICENSE AGREEMENT AND ASSOCIATED 

0022 * DOCUMENTATION. 

0023 * 


0024 

0025 

0026 
0030 
0043 

0051 

0052 

0053 

0054 

0055 

0056 

0057 

0058 

0059 

0060 
0061 
0062 

0063 

0064 

0065 

0066 

0067 

0068 

0069 

0070 

0071 

0072 


* ROUTINE NAME: DSRLP 

* 

* ABSTRACT: 

* FOR LPDIFF => 0 = 

* FOR LPDIFF <0 

* THIS IS THE HANDLER FOR I/O TO VARIOUS MODELS 
OF THE CENTRONICS AND TI LINE PRINTERS, THAT 

* USE AN RS-232-C INTERFACE. 

* 

* ENTRY: ENTERED VIA THE OPERATING SYSTEM THROUGH 

* DIFFERENT ENTRY POINTS. 

* 

* EXIT: VIA AN RTWP 

★ 

* ERRORS: >02 - ILLEGAL OPCODE 

* >04 - POWER LOST 

* >06 - REQUEST ABORTED 

* 

* REVISION: 07/18/80 - ORIGINAL 

* <REVISION DATE; LATEST LAST> - <NATURE> 

* 

* REVISION 02/04/81 - HANDLE "READ ONLY" 840,820 TERMINALS. 

* MAKE THIS DSR SMART ENOUGH TO RECOGNIZE 

* DC3 (BUSY) & DCI (READY) SIGNALS. 

* 01 07/30/81 -DNOS 1.1 

* ADD 9902 CONTROLLER COMMUNICATION 


/ 

Figure 5-1 4. DSR Listing Example (Sheet 1 of 1 6) 
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0073 

0074 

0075 

0076 

0077 

0078 

0079 

0080 
0081 
0082 

0083 

0084 

0092 

0093 

0094 

0095 

0096 

0097 

0098 

0099 

0100 
0101 
0102 

DSRLP 
DSRLP - 

0103 

0104 

0105 

0106 
0107 
0118 

0119 

0120 

0135 

0136 

0140 

0141 

0145 

0146 

0147 
0150 

0152 

0153 

0154 

0155 

0159 

0160 
0161 
0162 

0163 

0164 

0165 

0166 

0167 

0168 

0169 

0170 

0171 

0172 

0173 
DSRLP 
DSRLP 

0176 

0177 

0178 


03/22/82 - 
03/22/82 - 

03/23/82 - 
10/01/82 - 

02/25/83 - 

03/22/83 - 
03/28/83 - 
04/08/83 - 
04/21/83 - 
06/03/83 - 


* ENVIRONMENT; 


SDSMAC 3.5.0 82.130 
DNOS LINE PRINTER DSR 


990/10 

CALLAB 

TABLE 

16:53 


* SUBROUTINE REFS: 

REF ENDRCD 
REF BRSTAT 


- 'ADD CONDITIONAL ASSEMBLIES FOR DX10 
CODE. 

- CHANGE 9902 POWER UP TO SET 9902 FOR 
A 2.5 MHz CLK 

- FIX ALGORITHM AS TO WHEN IT IS SAFE 
TO CALL ENDRCD. 

- DON'T 00 LINE FEED ON OPEN 

- BE SURE EOR FLAG IS RESET WHEN A FORCE 
ENDRCD EXIT IS MADE. 

- ABORT PROCESS SHOULD SET EOR FLAG IF 

- ADO 9902 2-CHANNEL MUX SUPPORT 
PDTSRB IS NON-ZERO. 

- CORRECT SLOW DOWN OF PARALLEL INTERFAC 
PRINTERS. 

- 9902 GETS PROGRAMMABLE BAUD RATE 

- FIX BUGS 

- ABORT I/O CODE HAS BUGS 

- READST RETURNS STATISTICS 

- Fix lower case on parallel printer bug 

ASSEMBLER 

LE FROM ASSEMBLER 

SEGMENTS MAPPED IN WHEN ENTERED: 

:03 FRIDAY, JUN 17, 1983. 

PAGE 0003 

<STA, BTA, DSR COOE> 

SEGMENTS MAPPED IN DURING ROUTINE: 

<NONE> 


END-OF-RECORO ROUTINE 
BRANCH TABLE PROCESSOR 


* MACROS TO BE USED: 

LIBIN DSC. MACROS. TEMPLATE = 

LIBIN DSC. MACROS. FUNC 

* 

* EQUATES: 

ASMIF C$OS=C$DPOS = DNOS ONLY ================== 

COPY DSC. TEMPLATE. ATABLE.PDT 

* COPY DSC. TEMPLATE. ATABLE.IRB 

* COPY DSC. TEMPLATE. ATABLE.PDT 
0066 LPDBGN EQU PDTSIZ 

* COPY DSC. TEMPLATE. ATABLE. LPD = 

ASMEND ========================================== 

1 ASMIF C$OS=C$DX10 = DX10 ONLY =================== 

UNL 

COPY DSC. SYSTEM. TABLES. DSRPDT = 

COPY DSC. SYSTEM. TABLES. LPD = 

COPY DSC. SYSTEM. TABLES. DSRIRB 
LIST 

* COPY DSC. SYSTEM. TABLES. DSRPDT 

* COPY DSC. SYSTEM. TABLES. LPD 

* COPY DSC. SYSTEM. TABLES. DSRPDT 
LPDQCC EQU LPDCC 

LPDQIP EQU LPDIN 
LPDQOP EQU LPDOUT 
LPDIFF EQU LPDDMF 

SDSMAC 3.5.0 82.130 16:53:03 FRIDAY, JUN 17, 1983. 

DNOS LINE PRINTER DSR PAGE 0004 

* EIA CRU INPUT BIT DEFINITIONS 


0179 


♦ 


>0 

INPUT DATA (LSB) 



0180 


* 


>7 

INPUT DATA (MSB) 



0181 

0008 

EIAXMT 

EQU 

>8 

TRANSMIT IN PROGRESS 

(0=NO; 

1=YES) 

0182 

0009 

EIAERR 

EQU 

>9 

TIMING ERROR 

(0=NO; 

1=YES) 

0183 


★ 


>A 

REVERSE CHANNEL RECV 

(0=NO; 

1=YES) 

0184 


★ 


>B 

WRITE REQUEST 

(0=N0; 

1=YES) 

0185 


* 


>C 

READ REQUEST 

(0=NO; 

1=YES) 


Figure 5-1 4. DSR Listing Example (Sheet 2 of 1 6) 
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0186 

0187 

0188 

0189 

0190 

0191 

0192 

0193 

0194 

0195 

0196 

0197 

0198 

0199 

0200 
0201 
0202 

0203 

0204 

0205 

0206 

0207 

0208 

0209 

0210 
0211 
0212 

0213 

0214 

0215 

0216 

0217 

0218 

0219 

0220 
0221 
0222 

0223 

0224 

0225 

0226 

0227 

0228 

0229 

0230 

0231 

0232 

0233 

0234 

0235 
DSRLP 
DSRLP 

0236 

0237 

0238 

0239 

0240 

0241 

0242 

0243 

0244 

0245 

0246 

0247 

0248 

0252 

0253 

0254 
E0008 
E0009 
E0010 

0257 


OOOD 

EIAOCO 

EQU 

>0 

DATA CARRIER DETECT 

(0=NO; 1=YES) 

OOOE 

EIAOSR 

EQU 

>E 

DATA SET READY 

(0=NO; 1=YES) 


it 


>F 

MODULE INTERRUPT 

(0=NO; 1=YES) 


* - + - + 


+ 

+ 

+ 

+ 

+ 

+ 


-•f- + - + - + - + - + - + 


★ 

EIA 

CRU OUTPUT 

DEFINITIONS 




_ + _ + _ 

. + - + ^ + + ~ + - 

+ _ + _ + - + « + _ + _ + « + _ + _ + _ + 

- + - + - + - + - + - + 


* 


>0 

DATA TO MODULE (LSB) 


0007 

EIAPAR 

EQU 

>7 

DATA TO MODULE (MSB, 

PARITY BIT) 


* 


>8 

* NOT USED * 


0009 

EIADTR 

EQU 

>9 

DATA TERMINAL READY 

(0=OFF; 1=0N) 

OOOA 

EIARTS 

EQU 

>A 

REQUEST TO SEND 

(0=OFF; 1=0N) 

OOOB 

EIAWRQ 

EQU 

>B 

WRITE REQUEST (CLEAR) 

(0/1 CLEARS ) 

OOOC 

EIARRQ 

EQU 

>C 

READ REQUEST (CLEAR) 

(0/1 CLEARS ) 

OOOD 

EIANSF 

EQU 

>0 

NEW STATUS FLAG(CLEAR) (0/1 CLEARS ) 

OOOE 

EIAIEN 

EQU 

>E 

INTERRUPT ENABLE 

(0=0FF; 1=0N) 

OOOF 

EIADIM 

EQU 

>F 

DIAGNOSTICS MODE 

(0=0FF; 1=0N) 


★ 

- + - + - 

+ 

+ 

+ 

+ 

+ 

+ 




* 


* 

* 



* - + --f 


+-+-+-+-+-+ 



* 

DATA 

MODULE(OM) 

CRU OUTPUT BIT DEFINITIONS 




+-+-+-+-+-+ 



★ 


>0 

DATA TO MODULE (LSB) 


★ 


>6 

DATA TO MODULE (MSB) 

0007 

DMSTR 

EQU 

>7 

DATA STROBE (ASCII) 

0008 

DMSTRJ 

EQU 

>8 

DATA STROBE (JISCII) 

0009 

DMVFC 

EQU 

>9 

VERTICAL FROMS CONTROL 


* 


>A 



★ 


>B 



* 


>C 


OOOD 

DMDHD 

EQU 

>D 

DEMAND FOR A CHARACTER 

OOOE 

DMINT 

EQU 

>E 

INTERRUPT ENABLE BIT 

OOOF 

DMCIN 

EQU 

>F 

INTERRUPT ACKNOWLEDGE BIT 




* 9902 CRU INPUT BIT DEFINITIONS R01 

* _ + _4._ + - + « + - + _ + _ + .4._ + - + _ + «+_ + _+- + _+- + _ + _ + _ + _ + - + - + _ + _ + _ RQl 

* 


0022 

SECDCD 

EQU 

>22 

SECONDARY DATA CARRIER DETECT 

R01 

0020 

DCD902 

EQU 

>20 

DATA CARRIER DETECT 

R01 

001 B 

DSR902 

EQU 

>1B 

DATA SET READY 

R01 

0016 

XBRE 

EQU 

>16 

XMIT BUFR TEGISTER EMPTY 

R01 

0010 

RRQ902 

EQU 

>10 

READ REQUEST INTERRUPT 

R01 


★ - 

- + - + -■» 

+ 

1 

+ 

1 

+ 

1 

+ 

+ 

1 


R01 



9902 

CRU OUTPUT 

BIT DEFINITIONS 

R01 


★ 

. + - + -4 



R01 


* 




R01 

0027 

ABLTRS 

EQU 

>27 

ENABLE TRANSMISSIOS 

R01 

SDSMAC 

3.5.0 

82.130 16:53: 

03 FRIDAY, JUN 17, 1983. 


DNOS LINE PRINTER DSR 

PAGE 

0005 

0026 

INT902 

EQU 

>26 

INTERRUPT ENABLE 

R01 

0024 

CLOCK 

EQU 

>24 

1 = 2MHZ 

R06 


* 



0 = 4MHZ 

R06 

0022 

SECRTS 

EQU 

>22 

SECONDARY RTS 

R01 

0020 

OTR902 

EQU 

>20 

DATA TERMINAL READY 

R01 

001 F 

RESET 

EQU 

>1 F 

RESET CONTROLLER 

R01 

0015 

DSCENB 

EQU 

>15 

DATA SET STATUS CHANGE 

R01 


* 



INTERRUPT ENABLED 

R01 

0013 

XBIENB 

EQU 

>13 

XMIT BUFR REGISTER EMPTY 

R01 

0012 

RIENB 

EQU 

>12 

RCV'R INT ENABLE 



it 



INTERRUPT ENABLED 

R01 

0010 

RTS902 

EQU 

>10 

REQUEST TO SEND ON 

R01 







0003 

PR9902 

EQU 

3 

LPD FLAG 

R01 = 


* 



BIT 3 =1 -> 9902 CONTROLLED 

R01 = 


* GLOBAL DATA; 


= 



COPY 

DSC. TEMP LATE. COMMON. NFER10 




COPY 

DSC. TEMP LATE. COMMON. NFER20 




COPY 

DSC. TEMP LATE. COMMON. NFER30 




COPY 

DSC. TEMP LATE. COMMON. NFWORD 

= 


Figure 5-1 4. DSR Listing Exampie (Sheet 3 of 1 6) 
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0259 

0260 
0261 
0262 

0263 

0264 
DSRLP 
DSRLP 

0266 

0267 

0268 

0272 

0273 

0274 

0275 

0276 

0277 

0278 

0279 


COPY DSC. TEMPLATE. COMMON. NPERR1 
COPY DSC. TEMPLATE. COMMON. NFUORD 
ASMEND ==■«===*==»*■■*■*=■■ 


* NOTES: 

* 

SOSMAC 3.5.0 82.130 
DNOS LINE PRINTER DSR 


16:53:03 FRIDAY, JUN 17, 1983. 


PAGE 0006 


* ROUTINE NAME: DSRLP 


★ ABSTRACT; 


THIS IS THE MAIN ENTRY POINT INTO THE DSR FOR 
THE HARDWARE INTERRUPT (LPINT), SYSTEM INTERRUPT 
(LPINT), POWER RESTORE (PWRON) , ABORT I/O 
ROUTINE, (ABORT), REQUEST TIME OUT (ABORT), AND 
REQUEST PROCESSING. CERTAIN INITIALIZATION IS 
PERFORMED PRIOR TO PASSING CONTROL TO THE OP 
CODE HANDLING ROUTINE VIA "BRSTAT”. 


0280 

0000 

0460 



B 

8LPINT 

DSR 

HARDWARE INTERRUPT 


0002 

02C4' 







0281 

0004 

0460 



B 

SLPSINT 

DSR 

SOFTWARE INTERRUPT 


0006 

02CA' 







0282 

0008 

0460 



B 

aPWRON 

DSR 

POWER UP 


OOOA 

033C' 







0283 

OOOC 

0460 



B 

SABORT 

DSR 

ABORT 


OOOE 

0326' 







0284 

0010 

0460 



B 

aABORT 

DSR 

TIME OUT 


0012 

0326' 







0307 

0014 

04C5 



CLR 

R5 

INITIALIZE COUNTER 

0308 

0016 

0207 



LI 

R7,PAGE1 

INITIALIZE BUFFER 


0018 

0072' 







DSRLP 


SDSMAC 

3 

.5.0 

82.130 16:53:03 

FRIDAY, 

JUN 17, 1983. 

DSRLP 

- DNOS LINE 

PRINTER DSR 


PAGE 

0310 

001A 

020A 



LI 

RIO, STAB 

POINT TO STATISTICS TABLE 


001C 

004E' 







0311 

001 E 

06A0 



BL 

aBRSTAT 

DECODE OPCODE AND BRANCH 


0020 

0000 







0312 



*- 






0313 



* 

THE 

STATISTICS TABLE 

MUST BE MODIFIED IF THE OPCODE 

0314 



* 

TABLE IS 

MODIFIED. 



0315 









0316 

0022 

0013 

BASE 

DATA 

MAXCOD 


MAX OP CODE 

0317 

0024 

014E' 



DATA 

ILLOP 


ILLEGAL OP RETURN 

0318 

0026 

007C' 



DATA 

OPEN 

0 

OPEN 

0319 

0028 

007A' 



DATA 

CLOSE 

1 

CLOSE 

0320 

002A 

007E' 



DATA 

REWIND 

2 

CLOSE EOF 

0321 

002C 

0080' 



DATA 

OPNRWD 

3 

OPEN REWIND 

0322 

002E 

007E' 



DATA 

REWIND 

4 

CLOSE UNLOAD 

0323 

0030 

008A ' 



DATA 

READST 

5 

READ STATUS 

0324 

0032 

014E' 



DATA 

EXIT1 

6 

FWD SPACE - IGNORE 

0325 

0034 

014E' 



DATA 

EXIT1 

7 

BAK SPACE - IGNORE 

0326 

0036 

01 4E' 



DATA 

ILLOP 

8 

UNSED - ILLEGAL 

0327 

0038 

014E' 



DATA 

ILLOP 

9 

READ ASCII - ILLEGAL 

0328 

003A 

014E' 



DATA 

ILLOP 

A 

READ BINARY- ILLEGAL 

0329 

003 C 

0062' 



DATA 

WRITE 

B 

WRITE ASCII 

0330 

003E 

0062' 



DATA 

WRITE 

C 

WRITE DIRECT 

0331 

0040 

007E' 



DATA 

REWIND 

D 

WRITE EOF 

0332 

0042 

007E' 



DATA 

REWIND 

E 

REWIND 

0333 

0044 

014E' 



DATA 

EXIT1 

F 

UNLOAD - IGNORE 

0334 

0046 

014E' 



DATA 

ILLOP 

10 

UNUSED - ILLEGAL 

0335 

0048 

014E' 



DATA 

ILLOP 

11 

UNUSED - ILLEGAL 

0336 

004A 

014E' 



DATA 

ILLOP 

12 

UNUSED - ILLEGAL 

0337 

004C 

013C' 



DATA 

DUMP 

13 

DUMP STATISTICS 

0338 


0013 

MAXCOD 

EQU 

($-BASE-6)/2 



0339 

004E 

48 

STAB 

BYTE 

PDTMC 

0 

OPEN 

0340 

004F 

48 



BYTE 

PDTMC 

1 

CLOSE 

0341 

0050 

48 



BYTE 

PDTMC 

2 

CLOSE EOF 

0342 

0051 

48 



BYTE 

PDTMC 

3 

OPEN REWIND 

0343 

0052 

48 



BYTE 

PDTMC 

4 

CLOSE UNLOAD 

0344 

0053 

00 



BYTE 

0 

5 

READ STATUS 

0345 

0054 

00 



BYTE 

0 

6 

FWD SPACE 


0007 


R05 

R05 


R05 


Figure 5-14. DSR Listing Exampie (Sheet 4 of 16) 
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0346 

0055 

00 

BYTE 0 

7 

BAK SPACE 

0347 

0056 

00 

BYTE 0 

8 

* UNUSED * 

0348 

0057 

44 

BYTE POTRC 

9 

READ ASCII 

0349 

0058 

44 

BYTE PDTRC 

A 

READ DIRECT 

0350 

0059 

46 

BYTE POTWC 

B 

WRITE ASCII 

0351 

005A 

46 

BYTE POTWC 

C 

WRITE DIRECT 

0352 

005B 

46 

BYTE POTWC 

0 

WRITE EOF 

0353 

005C 

48 

BYTE PDTMC 

E 

REWIND 

0354 

005D 

00 

BYTE 0 

F 

UNLOAD 

0355 

005E 

00 

BYTE 0 

10 

* UNUSED * 

0356 

005F 

00 

BYTE 0 

11 

* UNUSED * 

0357 

0060 

00 

BYTE 0 

12 

* UNUSED * 

0358 

0061 

00 

BYTE 0 

13 

DUMP STATISTICS 

DSRLP 


SDSHAC 3. 

.5.0 82.130 16:53:03 

FRIDAY, 

JUN 17, 1983. 


OSRLP - DNOS LINE PRINTER DSR ' PAGE 0008 

0360 **0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0 

0361 * ABSTRACT: 


0362 



* 

WRITE 

- GET WRITE PARAMETERS FROM THE BRB. 



0363 



* 

CLOSE 

- ISSUE LF TO 

DUMP BUFFER. 



0364 



* 

OPEN 

- PURGE BUFFER 

AND DO CRLF. 



0365 



* 

REWIND - PAGE EJECT. 




0366 



* 

OPNRWD - PURGE BUFFER 

AND PAGE EJECT. 



0367 



* 

READST - RETURN PERTINANT INFORMATION 



0368 



if 

ILLOP 

- SET ERROR CODE AND RETURN. 



0369 



★ 

EXIT 

- CALL ENDRCD 

IF ALLOWABLE THEN EXIT 



0370 



* 

EXIT1 

- FORCE ENDRCD 

CALL AND EXIT 


R05 

0371 



★ 






0372 



**0=0=1 

0=0=0= 

il 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

o 

II 

o 

II 

o 

II 

o 

11 

o 

II 

o 

II 

o 

11 

o 

II 

o 

II 

o 

II 

o 

II 

o 

11 

0=0=0 

=0 

0373 

0062 

C1E1 

WRITE 

MOV 

SIRBDBA(R1 ) ,R7 

BUFFER ADDRESS 




0064 

0006 







0374 

0066 

C161 


MOV 

aiRBOCCCRl) ,R5 

CHARACTER COUNT 




0068 

OOOA 







0375 

006A 

C845 


MOV 

R5,SIRBICC(R1) 

ACTUAL CHAR COUNT OUTPUT 



006C 

0008 







0376 

006E 

136F 


JEQ 

EXIT1 

CHAR COUNT = 0..EXIT 



0377 

0070 

1008 


JMP 

NEWREQ 




0378 



it 






0379 

0072 

ODOC 

PAGE1 

DATA 

>0D0C NULL/FORM FEED 



0380 

0074 

ODOC 

PAGE2 

DATA 

>0D0C CARRIAGE RETURN/FORM FEED 



0381 

0076 

ODOD 

CR 

DATA 

>0D0D NULL /CARRIAGE RETURN 


R04 

0382 

0078 

ODOD 

CRLF 

DATA 

>0D0D NULL/CARRIAGE RETURN 



0383 



* 






0384 

007A 

05C7 

CLOSE 

INCT 

R7 

SET BUFFER POINTER 

(CRLF 

) 

0385 

007C 

05C7 

OPEN 

INCT 

R7 

SET BUFFER POINTER 

(CR 

) 

0386 

007E 

05C7 

REWIND 

INCT 

R7 

SET BUFFER POINTER 

(PAGE2) 

0387 

0080 

05C5 

OPNRWD 

INCT 

R5 

SET CHARACTER COUNT 

(PAGE1 > 

0388 

0082 

0286 

NEWREQ 

Cl 

R6,LPSPUR 

IS AN INTERRUPT EXPECTED? 



0084 

03A0' 







0389 

0086 

1378 


JEQ 

TSTDSR 

MO, START OUTPUT 



0390 

0088 

0380 


RTWP 


YES, EXIT DSR 



0391 



* 






0392 

008A 

C1E1 

READST 

MOV 

aiRBDBACRI ) ,R7 

GET BUFFER POINTER 


R13 


008C 

0006 







0393 

008E 

04E1 


CLR 

aiRBOCC(RI) 

CLEAR OUTPUT BUFFER LENGTH 

R13 


0090 

OOOA 







0394 

0092 

0208 


LI 

R8,>OOFF 

RESERVED WORD 


R13 


0094 

OOFF 







0395 

0096 

06A0 


BL 

aRFILLI 



R13 


0098 

OIOC 







0396 

009A 

04C8 


CLR 

R8 



R13 

0397 

009C 

06A0 


BL 

aRFILLI 

CLEAR NEXT WORD 


R13 


009E 

OIOC 







0398 

OOAO 

0208 


LI 

R8,>0100 

THIS IS A PRINTER DSR 


R13 


OOA2 

0100 







0399 

00A4 

06A0 


BL 

aRFILLI 

PUT WORD IN BUFFER 


R13 


00A6 

OIOC 







0400 

00A8 

C20C 


MOV 

R12,R8 

CRU ADDRRESS GOES NEXT 


R13 

0401 

OOAA 

06A0 


BL 

aRFILLI 

STORE WORD 


R13 


OOAC 

OIOC 







0402 

OOAE 

0208 


LI 

R8,>FFFF 

RESERVED FIELD 


R13 


OOBO 

FFFF 







0403 

00B2 

06A0 


BL 

aRFILLI 



R13 
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00B4 

010C' 






0404 

00B6 

0208 


LI 

R8,>0500 

ASSUME EIA INTERFACE 

R13 


00B8 

0500 






OSRLP 


SDSMAC 

3.5.0 

82.130 16:53:03 

FRIDAY, JUN 17, 1983. 


DSRLP 

- DNOS LINE PRINTER DSR 

PAGE 

0009 

0405 

OOBA 

C164 


MOV 

aLPDIFF(R4) , 

R5 GET INTERFACE FLAGS 

R13 


OOBC 

0066 






0406 

OOBE 

2160 


COC 

aLPF902*2+MASTAB,R5 IS THIS A 9902 ? 

R13 


OOCO 

0028+ 






0407 

00C2 

1602 


JNE 

R0ST10 

IF NOT, SKIP 

R13 

0408 

00C4 

0208 


LI 

R8,>0600 

SET UP FOR A 9902 INTRFCE 

R13 


00C6 

0600 






0409 

00C8 


ROST10 

EVEN 



R13 

0419 

00C8 

2560 


cze 

aLPFIF*2+MASTAB,R5 IS THIS PARALLEL ? = 

R13 


OOCA 

0022+ 






0420 

OOCC 

1602 


JNE 

RDST20 

IF NOT, SKIP 

R13 

0424 

OOCE 

0208 


LI 

R8,>8000 

SET UP FOR PARALLEL 

R13 


OODO 

8000 






0425 

0002 

06A0 

RDST20 

BL 

aRFILLI 

ONE WORD TO STORE 

R13 


0004 

OIOC 






0426 

0006 

04C8 


CLR 

R8 

6 WORDS OF ZEROS 

R13 

0427 

0008 

0205 


LI 

R5,6 


R13 


OODA 

0006 






0428 

OODC 

06A0 


BL 

aRFILL 


R13 


OODE 

0110' 






0429 

OOEO 

0224 


MOVB 

aLPDSPX(R4) , 

R8 GET XMIT BAUD RATE 

R13 


00E2 

0076 






0430 

00E4 

06A0 


BL 

aRFILLI 

STORE IN OUTPUT BUFFER 

R13 


00E6 

OIOC 






0431 

00E8 

04C8 


CLR 

R8 


R13 

0432 

OOEA 

0205 


LI 

R5,12 

12 WORDS OF ZEROS 

R13 


OOEC 

OOOC 






0433 

OOEE 

06A0 


BL 

aRFILL 


R13 


OOFO 

0110' 






0434 

00F2 

C204 


MOV 

R4,R8 

GET POT POINTER 

R13 

0435 

00F4 

0228 


AI 

R8,PDTRC 

POINT AT READ COUNT 

R13 


00F6 

0044 






0436 

00F8 

0205 


LI 

R5,6 

6 BYTES TO COPY 

R13 


OOFA 

0006 






0437 

OOFC 

06A0 


BL 

aRCOPY 


R13 


OOFE 

0126' 






0438 

0100 

04C8 


CLR 

R8 

FINALLY, FOUR MORE ZEROS 

R13 

0439 

0102 

0205 


LI 

R5,4 


R13 


0104 

0004 






0440 

0106 

06A0 


BL 

aRFILL 


R13 


0108 

0110' 






0441 

01 OA 

1021 


JMP 

EXIT1 


R03 

0442 



•k 




R13 

0443 



k 

TO AID IN THE CONSTRUCTION OF THE STATUS RETURN 

R13 

0444 



k 

BUFFER, WE HAVE RFILL AND RCOPY. R7 S JOB IS TO 

R13 

0445 



k 

POINT AT THE OUTPUT BUFFER. 

R13 

0446 



k 


RFILL - STORE R8 INTO BUFFER R5 TIMES 

R13 

0447 



k 


RCOPY - COPY 

R5 BYTES FROM *R8 TO BUFFER 

R13 

0448 



k 

SHOULD THE BUFFER 

BECOME FULL AT ANY TIME, RFILL 

R13 

0449 



k 

AND 

RCOPY TAKE THE LIBERTY TO TERMINATE THE SVC 

R13 

0450 



k 

AND 

RETURN WITH WHATEVER INFORMATION MADE IT INTO 

R13 

0451 



k 

THE 

BUFFER. 


R13 

0452 



k 




R13 

0453 

010C 

0205 

RFILL1 

LI 

R5,1 

FOR ONE WORD STORES 

R13 


010E 

0001 






0454 

0110 

8861 

RFILL 

C 

aiRBOCC(RI), 

aiRBICC(RI) BUFFER FULL ? 

R13 


0112 

OOOA 







0114 

0008 






0455 

0116 

1516 


JGT 

EXIT 

IF SO, BLOW THIS 

R13 

0456 

0118 

1315 


JEQ 

EXIT 

POPSICKLE STAND 

R13 

DSRLP 


SDSMAC 

3.5.0 

82.130 16:53:03 

FRIDAY, JUN 17, 1983. 


OSRLP 

- DNOS LINE PRINTER DSR 

PAGE 

0010 

0457 

011A 

C0C8 


MOV 

R8,*R7+ 

ELSE, DO MORE FILLING 

R13 

0458 

one 

05E1 


INCT 

aiRBOCCCRI ) 

KICK COUNTER HARD 

R13 


011E 

OOOA 






0459 

0120 

0605 


DEC 

R5 

DONE YET ? 

R13 

0460 

0122 

16F6 


JNE 

RFILL 

IF NOT, HIT IT AGAIN 

R13 


Figure 5-14. DSR Listing Example (Sheet 6 of 16) 



Writing a DSR 


0461 

0124 

0458 


8 

*R11 ELSE, RETURN FOR MORE 

R13 

0462 



* 



R13 

0463 

0126 

8861 

RCOPY 

C 

aiR80CC(R1),aiR8ICC(R1) SUFFER FULL ? 

R13 


0128 

OOOA 






012A 

0008 





0464 

012C 

1508 


JGT 

EXIT IF SO, EXIT STAGE LEFT 

R13 

0465 

012E 

130A 


JEQ 

EXIT (WE REALY NEED JGE) 

R13 

0466 

0130 

0DF8 


M0V8 

+R8+,*R7+ ELSE, PLAGIARIZE PDT 

R13 

0467 

0132 

05A1 


INC 

aiROOCC(Rl) KICK COUNTER 

R13 


0134 

OOOA 





0468 

0136 

0605 


DEC 

R5 DONE YET ? 

R13 

0469 

0138 

16E8 


JNE 

RFILL IF NOT, LOOP FOR MORE 

R13 

0470 

013A 

0458 


8 

*R11 ELSE, RETURN TO MAIN CODE 

R13 

0471 



* 



R13 

0472 

013C 

0920 

DUMP 

M0V8 

aWDFFFF,aPDTERR<R4) 



013E 

0020 + 






0140 

0042 





0473 

0142 

1005 


JMP 

EXIT1 

R03 

DSRLP 


SDSMAC 

3.5.0 

82.130 16:53:03 FRIDAY, JUN 17, 1983. 


DSRLP 

- DNOS LINE PRINTER DSR PAGE 

0011 

0475 



it-kitir 




0476 



ir 




0477 



* EXIT 

ROUTINE 


0478 



* 




0479 



it ft kit 




0480 



*+*EXIT MOV R5,R5 HAVE OUTPUT CHARS 8EEN SUFFERED? 

R03 

0481 



it it it 

JNE 

DONE 

R03 

0482 



kkit 

MOV 

aP0TSR8(R4) ,R1 IS THERE AN OUTSTANDING REQ? R03 

0483 



★ ★★ 

JEQ 

DONE 

R03 

0484 



kfcit 

MOV 

aiR80C(R1) ,R11 YES, THIS AN OPEN/CLOSE? 

R03 

0485 



itftit 

Cl 

R11 ,>04FF 

R03 

0486 



itkit 

JLE 

EXIT01 

R03 

0487 



it 


END OF RECORD TO 8E DONE 

R03 

0488 



ititfc 

MOV 

aiR8S0C(Rl ) ,R11 YES, ERRORRED OFF? 

R03 

0489 



it it it 

JNE 

EXIT1 


0490 



it it it 

MOV 

aLPDQCC(R4) ,R11 NO, ALL CHARS SEEN OUTPUT? 

0491 



ititk 

JNE 

DONE 


0492 



it 


TURN OFF EOR FLAG. 

R03 

0496 

0144 

C2E4 

EXIT 

MOV 

aLPDIFF(R4) ,R11 

R03 


0146 

0066 





0497 

0148 

22E0 


COC 

aLPFE0R+2+MASTA8,R11 

R03 


01 4A 

002A + 





0498 

014C 

1605 


JNE 

DONE -NO. 

R03 

0499 



* 


RESET EOR FLAG 

R03 

0500 


014E' 

ILLOP 

EQU 

$ 

R05 

0501 

01 4E 

4920 

EXIT1 

SZC 

aLPFE0R*2+MASTA8,aLPDIFF(R4) 

R05 


0150 

002A+ 






0152 

0066 





0513 

0154 

06A0 


8L 

aENDRCD YES, GO TO END-OF-RECORD ROUTINE 


0156 

0000 





0514 

0158 

0380 

DONE 

RTUP 



DSRLP 


SDSMAC 

3.5.0 

82.130 16:53:03 FRIDAY, JUN 17, 1983. 


DSRLP 

- DNOS LINE PRINTER DSR PAGE 

0012 

0516 



**0=0= 

0=0=0 

=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0=0 

=0=0 

0517 



* A8STRACT 

: ' 


0518 



* 

TSTWRQ - THIS ROUTINE IS ENTERED UPON RECEIPT OF 

AN 

0519 



* 


INTERRUPT FROM AN EIA INTERFACED LP. WRITE 

0520 



* 


REQUEST MUST GO HIGH 8EF0RE PRECEEDING TO 


0521 



* 


OUTPUT ANOTHER CHARACTER. 


0522 



it 

TSTDSR - THIS ROUTINE IS ENTERED UPON RECEIPT OF 

AN 

0523 



it 


INTERRUPT FROM A DM INTERFACED LP, WRITE 


0524 



it 


REQUEST FOR AN EIA I/F*D LP HAS GONE HIGH, 

OR 

0525 



it 


THIS IS THE INITIAL CHARACTER 8EING OUTPUT 

TO 

0526 



it 


THE LP. 


0527 



* 




0528 



**0=0= 

o 

II 

o 

II 

o 

II 

o 

II 

o 

11 

o 

II 

o 

II 

o 

11 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

11 

o 

II 

o 

II 

o 

II 

o 

II 

o 

11 

o 

II 

o 

11 

o 

II 

o 

II 

o 

11 

o 

=0=0 

0529 



* 




0530 

015A 

C2A4 

TSTWRQ 

MOV 

aLPDIFF<R4) ,R10 IS THIS 9902 CONTROLLED 

R01 


015C 

0066 





0531 

015E 

0A4A 


SLA 

RIO, LPF902+1 

R01 

0532 

0160 

1706 


JNC 

TSTW05 -NO. JUMP 

R01 

0533 

0162 

1F16 


T8 

X8RE XMIT 8UFFER EMPTY? 

R01 


Figure 5-14. DSR Listing Exampie (Sheet 7 of 16) 


2270510-9701 
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Writing a DSR 


0534 

0164 

1309 


JEQ 

TSTDSR 

-YES. 

R01 

0535 

0166 

1D13 


SBO 

XBIENB 


R01 

0536 

0168 

1D10 


SBO 

RTS902 


R01 

0537 

01 6A 

0460 


B 

aTST480 

-NO. EXIT.. WAIT 

R01 


016C 

0270' 






0538 



* 





0539 

016E 

1 FOB 

TSTW05 

TB 

EIAURQ 

WRITE REQUEST HIGH? 

R01 

0540 

0170 

1302 


JEQ 

TSTWR1 


MAR 

0541 

0172 

0460 


B 

8TST480 

NO, WAIT FOR IT 

MAR 


0174 

0270' 






0542 

0176 

1E0B 

TSTWR1 

SBZ 

EIAWRQ 

YES, RESET IT 


0543 



* 





0547 

0178 

C2A4 

TSTOSR 

MOV 

SLP0QEP(R4) ,R10 

GET QUEUE END POINTER 

s 


01 7A 

006E 






0558 

017C 

C264 

TSTRR9 

MOV 

aLPDQIP(R4),R9 

GET QUEUE INPUT POINTER 



017E 

006A 






DSRLP 


SDSMAC 

; 3.5.0 

82. 

130 16:53:03 FRIDAY, JUN 17, 1983. 


DSRLP 

- DNOS LINE PRINTER 

DSR 

PAGE 

0013 

0560 



* 





0561 



* BUFFER 

THE DATA IF POSSIBLE 


0562 








0563 

0180 

C145 


MOV 

R5,R5 

ANY DATA TO BUFFER? 


0564 

0182 

130E 


JEQ 

TST030 

NO 


0565 

0184 

824A 

TST010 

C 

R10,R9 

YES, AT END OF BUFFER? 


0566 

0186 

1B01 


JH 

TST020 

NO 


0570 

0188 

625A 


S 

*R10,R9 

YES, PUT POINTER AT BEGINNING= 

0571 

018A 

86A4 

TST020 

C 

aLPDQCC(R4) ,*R10 

IS THE BUFFER FULL? 

= 


018C 

0068 






0582 

018E 

1308 


JEQ 

TST030 

YES 


0583 

0190 

DE77 


MOVB *R7+,*R9+ 

NO, MOVE NEXT CHAR TO BUFFER 

0584 

0192 

05A4 


INC 

aLPDQCC(R4) 

...COUNT IT 



0194 

0068 






0585 

0196 

0605 


DEC 

R5 

...REDUCE INPUT COUNT 


0586 

0587 

0198 

15F5 

* 

JGT 

TST010 

ALL THE DATA IS BUFFERED 

R03 

0588 



* 



SET END-OF-RECORD FLAG. 

R03 

0589 



* 



ENDRCD CAN NOW BE CALLED. 

R03 

0593 

019A 

E920 


SOC 

aLPFE0R*2+MASTAB, 

,aLPDIFF(R4) 

R03= 


019C 

002A+ 







019E 

0066 






OSRLP 


SDSMAC 

3.5.0 

82. 

130 16:53:03 FRIDAY, JUN 17, 1983. 


DSRLP 

- DNOS LINE PRINTER 

DSR 

PAGE 

0014 

0603 

01A0 

C909 

TST030 

MOV 

R9,aLPDQIP(R4) 

SAVE QUEUE INPUT POINTER 



01A2 

006A 






0604 

01A4 

0206 


LI 

R6,LPSPUR 

INITIALIZE INTERRUPT VECTOR 


01A6 

03A0' 






0605 

01A8 

C224 


MOV 

aLPDQCC(R4) ,R8 

ANY DATA TO OUTPUT? 



01 AA 

0068 






0606 01AC 1602 

JNE 

TST035 

R01 

0607 

01AE 

0460 


B 

aTST480 

NO 

R01 


01B0 

0270' 






0608 

01B2 

C224 

TST035 

MOV 

aLPDQ0P(R4) ,R8 

YES, GET QUEUE OUTPUT POINTER 


01B4 

006C 






0609 

01B6 

820A 


C 

R10,R8 

AT END OF BUFFER? 


0610 

01B8 

1B01 


JH 

TST040 

NO 


0614 

01 BA 

621A 


S 

*R10,R8 

YES, POINTER TO BEGINNING 

= 

0623 

01BC 

0206 

TST040 

LI 

R6, TSTDSR 

INITIALIZE INTERRUPT VECTOR 


01BE 

0178' 






0627 

01C0 

C024 


MOV 

aLPDIFF(R4) ,R0 

DM INTERFACED LP? 



01C2 

0066 






0628 

01C4 

1505 


JGT 

DMOUT 

-YES. 

R01 

0629 

01C6 

1304 


JEQ 

DMOUT 

-YES. 

R01 

0640 

0641 

01C8 

2020 

* 

COC 

aLPF902*2+MASTAB, 

,R0 

R01 


01 CA 

0028+ 






0642 



* 



IS THIS 9902 CONTROLLED 

R01 

0643 

01CC 

1328 


JEQ 

0UT902 

-YES. JUMP 

R01 

0644 

01 CE 

103C 


JMP 

EIAOUT 

-NO. MUST BE EIA 

R01 


DSRLP SDSMAC 3.5.0 82.130 16:53:03 FRIDAY, JUN 17, 1983. 

OSRLP - ONOS LINE PRINTER OSR PAGE 0015 

0646 * 

0647 * OUTPUT TO DATA MODULE (DM) INTERFACE 




Figure 5-1 4. DSR Listing Example (Sheet 8 of 1 6) 
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2270510-9701 



Writing a DSR 


0648 




- 





0649 


0100' 

OMOUT 

EQU 

$ 



09 

0650 

01 DO 

1 FOD 


TB 

DMOMD 


DEMAND UP? 


0651 

01 02 

134E 


JEQ 

TST480 


NO, GO EXIT DSR 


0652 

01D4 

0278 


MOVB 

+R8+,R9 


YES, PICKUP NEXT OUTPUT CHAR 

0653 

0106 

0A20 


SLA 

RO, LPFUC+1 


MAP LOWERCASE TO UPPERCASE? 

0654 

0108 

1808 


JOC 

TST210 


NO 


0655 

010A 

0289 


Cl 

R9,>6100 


YES 



OlDC 

6100 







0656 

01DE 

1A05 


JL 

TST210 




0657 

01EO 

0289 


Cl 

R9,>7B00 





01E2 

7B00 







0658 

01 E4 

1402 


JHE 

TST210 




0659 

01 E6 

0249 


ANOI 

R9,#>2000 





01 E8 

DFFF 







0660 

01 EA 

0549 

TST210 

INV 

R9 


INVERT THE CHARACTER 


0661 

01EC 

20A0 


COC 

aDSFJIS*2+MASTAB, 

,R2 

FE 


01EE 

002A+ 







0662 



* 




IS IT JISCII TERMINAL? 

FE 

0663 

01 FO 

1605 


JNE 

TST220 



FE 

0664 

01F2 

3209 


LDCR 

R9,8 


YES, OUTPUT 8 BITS 


0665 

01 F4 

1E08 


SBZ 

OMSTRJ 


STROBE THE INTERFACE 


0666 

01 F6 

1000 


NOP 





0667 

01F8 

1008 


SBO 

DMSTRJ 




0668 

01 FA 

1004 


JMP 

TST240 




0669 



★ 






0670 

01 FC 

31C9 

TST220 

LDCR 

R9,7 


NO, OUTPUT 7 BITS 


0671 

01FE 

1E07 

TST230 

SBZ 

DMSTR 


STROBE THE INTERFACE 


0672 

0200 

1000 


NOP 





0673 

0202 

1007 


SBO 

DMSTR 




0674 

0204 

C908 

TST240 

MOV 

R8,SLPDQ0P(R4) 

UPDATE OUTPUT POINTER 



0206 

006C 







0675 

0208 

0624 


DEC 

aLPDQCC(R4} 


REDUCE QUEUE OUTPUT COUNT 



020A 

0068 







0676 

020C 

13B5 


JEQ 

TSTDSR 


GO BUFFER MORE DATA 

09 

0677 

020E 

C024 


MOV 

aLPDIFF(R4) , 

RO 

Grab interface flags 

14 


0210 

0066 







0678 

0212 

8288 


C 

R8,R10 


AT END OF BUFFER? 

09 

0679 

0214 

1600 


JNE 

OMOUT 


NO-CONTINUE PRINTING 

09 

0683 

0216 

621A 


S 

*R10,R8 


YES, RESET POINTER 

09 

0692 

0218 

C908 


MOV 

R8,aLPDQ0P(R4> 

UPDATE OUTPUT POINTER 

09 


021A 

006C 







0693 

021C 

1009 


JMP 

OMOUT 


MOVE NEXT CHAR 

09 

DSRLP 


SDSMAC 

3.5.0 

82.130 16:53:03 

FRIDAY, JUN 17, 1983. 


DSRLP 

- DNOS LINE PRINTER DSR 


PAGE 

0016 

0695 









0696 



* OUTPUT TO 9902 INTERFACE 



0697 



------ 






0698 



★ 






0699 



* 




IS PRINTER BUSY? 


0700 

021 E 

2020 

OUT902 

COC 

aLPFBSY*2+MASTAB, 

,R0 



0220 

0026+ 







0701 

0222 

1302 


JEQ 

OUT100 



R01 

0702 

0224 

1 FIB 


TB 

DSR902 


DATA SET READY? 

R01 

0703 

0226 

1303 


JEQ 

OUT200 



R01 

0704 

0228 

1E13 

0UT100 

SBZ 

XBIENB 


-NO. DISABLE XMIT BUFF INT 

R01 

0705 

022A 

1015 


SBO 

DSCENB 


ENABLE OAT SET READY INT 

R01 

0706 

022C 

1021 


JMP 

TST480 



R01 

0707 

022E 

C28B 

0UT200 

MOV 

R11 ,R10 



R01 

0708 

0230 

1013 


SBO 

XBIENB 




0709 

0232 

06A0 


BL 

aLPCOMN 



R01 


0234 

0274* 







0710 

0236 

C2CA 


MOV 

RIO.RII 




0711 

0238 

0249 

OUT410 

ANOI 

R9,>7F00 



R01 


023A 

7F00 







0712 



* 





R01 

0713 

023C 

3209 


LDCR 

R9,8 


SEND THE CHARACTER 

R01 

0714 

023E 

C908 


MOV 

R8,aLPDQ0P(R4) 

UPDATE OUTPUT POINTER 

R01 


0240 

006C 







0715 

0242 

0624 


DEC 

aLP0QCC(R4) 


REDUCE QUEUE CHAR COUNT 

R01 


0244 

0068 







0716 

0246 

1014 


JMP 

TST480 


EXIT 

R01 


Figure 5*1 4. DSR Listing Example (Sheet 9 of 1 6) 
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Writing a DSR 


0717 




— 




0718 



* 

OUTPUT TO EIA INTERFACE 


0719 





- 



0720 



* 




RO = aLP0IFF(R4> 

0721 



* 




IS PRINTER BUSY? 

0722 



* 




("RO" TERMINAL) 

0723 

0248 

2020 

EIAOUT 

coc 

aLPFBSY*2+MASTAB, 

RO 


024A 

0026+ 






0724 

024C 

1311 



JEQ 

TST480 

YES 

0725 

024E 

1 FOE 



TB 

EIAOSR 

' 'OATA SET REAOY" ON ?? 

0726 

0250 

160F 



JNE 

TST480 

NO 

0727 

0252 

C28B 



MOV 

R11 ,R10 


0728 

0254 

06A0 



BL 

SLPCOMN 



0256 

0274* 






0729 

0258 

C2CA 



MOV 

R10,R11 


0730 

025A 

0249 



ANOI 

R9,>7F00 



025C 

7F00 






0731 

025E 

31C9 



LOCR 

R9,7 

LOAO CHARACTER 

0732 

0260 

1C02 



JOP 

TST440 

SET PARITY BIT AS NEEOEO 

0733 

0262 

1E07 



SBZ 

EIAPAR 


0734 

0264 

1001 



JMP 

TST450 


0735 

0266 

1D07 

TST440 

SBO 

EIAPAR 


0736 

0268 

C908 

TST450 

MOV 

R8,SLP0Q0P(R4) 

UPOATE OUTPUT POINTER 


026A 

006C 






0737 

026C 

0624 



OEC 

aLP0QCC(R4) 

REOUCE QUEUE CHARACTER COUNT 


026E 

0068 






0738 

0270 

0460 

TST480 

B 

aEXIT 

PERFORM ENO OF REQUEST 


0272 

0144* 






DSRLP 


SDSMAC 

3 

.5.0 

82.130 16:53:03 FRIOAY, JUN 17, 1983. 

OSRLP 

- DNOS LINE 

PRINTER OSR 

PAGE OOV 

0740 



* 





0741 



★ - 



■- 


0742 



★ 

LPCOMN 

- COMMON ROUTINE 

USEO BY 9902 ANO EIA PRINTERS 

0743 



* 



1) PROCESS EXTENOEO CHARACTER SET.. IF ANY 

0744 



* 



2> CHECK ANO PROCESS KATAKANA 

0745 



★ - 

— 




0746 

0274 

0206 

LPCOMN 

LI 

R6,TSTWRQ 

SET INTERRUPT VECTOR 


0276 

015A' 






0747 

0278 

0278 



MOVB 

*R8+,R9 

NEXT OUTPUT CHAR 

0748 

027A 

0A20 



SLA 

RO, LPFUC+1 

EXTENOEO CHARACTER SET 

0749 

027C 

1808 



JOC 

LPC410 

-YES. JUMP 

0750 

027E 

0289 



Cl 

R9,>6100 

-NO. MAP LOWERCASE TO 


0280 

6100 






0751 

0282 

1A05 



JL 

LPC410 

UPPERCASE? 

0752 

0284 

0289 



Cl 

R9,>7B00 



0286 

7B00 






0753 

0288 

1402 



JHE 

LPC410 


0754 

028A 

0249 



ANOI 

R9.#>2000 


028C DFFF 






0755 



★ 




IS THIS A JISCII TERMINAL 

0756 

028E 

20A0 

LPC410 

COC 

aOSFJIS+2+MASTAB, 

R2 


0290 

002A+ 






0757 

0292 

1617 



JNE 

LPC430 


0784 

0294 

0249 



MOVB 

R9,R9 

KATAKANA CHARACTER? 

0785 

0296 

110B 



JLT 

LPC420 

YES 

0786 



•k 




PRINTER IN ALPHA MOOE 

0787 

0298 

20A0 



COC 

aOSFJAR*2+MASTAB, 

R2 


029A 

002E+ 






0788 

029C 

1612 



JNE 

LPC430 

YES 

0789 

029E 

0242 



ANOI 

R2,#(>8000//OSFJAR) NO, RESET TO ALPHA 


02A0 

FOFF 






0790 

02A2 

0209 



LI 

R9,>0F00 

LOAO SHIFT IN COOE 


02A4 

OFOO 






0791 

02A6 

0608 



OEC 

R8 

RESET QUEUE OUTPUT POINTER 

0792 

02A8 

05A4 



INC 

aLP0QCC(R4) 

AOJUST QCC 


02AA 

0068 






0793 

02AC 

100A 



JMP 

LPC430 


0794 



* 





0795 



* 




PRINTER IN KATAKANA MOOE? 

0796 

02AE 

20A0 

LPC420 

COC 

aOSFJAR*2+MASTAB, 

R2 


02B0 

002E+ 






0797 

02B2 

1307 



JEQ 

LPC430 

YES 
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0798 

0799 

0800 
0801 

0805 

DSRLP 

OSRLP 

0807 

0808 

0809 

0810 
0811 
0812 

0813 

0814 

0815 

0816 

0817 

0818 

0819 

0820 
0821 
0822 

0823 

0824 

0825 

0826 

0827 

0828 

0829 

0830 

0831 


0832 

0842 

0846 

0847 

0848 

0849 

0850 

0851 

0852 

0853 

0854 

0855 

0856 

0857 

0858 

0859 

0860 
0861 
0862 

0863 

0864 

0865 

0866 

0867 

0868 

0869 

0870 


0871 

DSRLP 

DSRLP 


02B4 

0262 

ORI 

R2,>8000//DSFJAR 

NO, SET 

TO KATAKANA 


02B6 

0200 






02B8 

0209 

LI 

R9,>0E00 

LOAD SHIFT 

OUT CODE 


02BA 

OEOO 






02BC 

0608 

DEC 

R8 

RESET QUEUE 

OUTPUT POINTER 


02BE 

05A4 

INC 

aLPDQCC(R4) 

ADJUST QCC 


= 

02C0 

0068 






02C2 

045B 

LPC430 B 

*R11 
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** 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 * 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 = 0 » 0 = 0 = 0 = 0 = 0 = 0=0 

* ABSTRACT: 

* LPINT - THIS IS THE ENTRY POINT FOR DEVICE 

* INTERRUPT. THE TIME-OUT COUNTER IS RESET AND 

* THE PROPER ROUTINE IS ENTERED VIA R6. 

* 

* A BUSY FLAG HAS BEEN ADDED TO THE LPD FOR 

* "READ ONLY" (RO) TERMINALS, 

* THIS FLAG IS ON WHENEVER A DC3(BUSY) INTERRUPT IS 

* ISSUED BY THE TERMINAL. A DC1 (READY) INTERRRUPT 

* CAUSES THE FLAG TO BE RESET. 

* THE BUSY FLAG IS ALSO RESET WHENEVER "DATA SET" 

* RE "DSR" IS NOT ON, DUE TO THE FACT THAT WHEN 

* THE TE IS TAKEN OFFLINE THEN ONLINE A DC1 IS NOT 

* SENT. "DSR" AND BUSY ARE CHECKED IN THE WRITE 

* ROUTINE I PWRON - THIS ROUTINE IS ENTERED WHEN 

* THE SYSTEM INITIALLY STARTS AND WHEN THE SYSTEM 

* RECOGNIZES A POWER RE-START. THE INTERFACE IS 

* PROPERLY INTIALIZED. 

* LPSPUR - HANDLE SPURIOUS INTERRUPTS. 




* 

ABORT - THIS ROUTINE 

HANDLES I/O ABORT. 




★ *0=0^= 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

II 

o 

11 

o 

II 

o 

II 

o 

II 

o 

=0=0=0=0=0=0=0=0=0=0=0=0=0=0 

1=0 

02C4 

C924 

LPINT 

MOV 

aPDTTMl (R4) ,aPDTTM2<R4) RESET TIME OUT COUNT 


02C6 

0056 






02C8 

0058 






02CA 

C024 

LPSINT 

MOV 

aLPDIFF(R4) ,R0 

DM INTERFACED LP ? 


02CC 

0066 






02CE 

1102 


JLT 

LPI1 

NO 

s 

02D0 

1E0F 


SBZ 

DMCIN 

YES, CLEAR INPUT INTERRUPT 

02D2 

0456 

★ 

B 

*R6 

9902 CONTROLLED 

R01 

02D4 

0A40 

LPI1 

SLA 

R0,LPF902+1 


R01 

02D6 

1706 


JNC 

LPI010 

-NO. JUMP 

R01 

02D8 

1D13 


SBO 

XBIENB 

ENABLE XMIT BUFER INT 

R01 

02DA 

1D15 


SBO 

DSCENB 

DISABLE DATA SET READY INT 

R01 

02DC 

1 F10 


TB 

RRQ902 

READ REQUEST INTERRUPT 

R01 

02DE 

1616 


JNE 

LPI040 

-NO. JUMP 

R01 

02E0 

1D12 


SBO 

RIENB 

-YES. CAUSES RRQ902 TO 

R01 



★ 



RESET 

R01 

02E2 

1004 


JMP 

LPI020 


R01 

02E4 

1EOO 

LPI010 

SBZ 

EIANSF 

CLEAR NEW STATUS INT 




* 



CHECK FOR "RO" TERMINAL 

FE 

02E6 

1 FOC 


TB 

EIARRQ 

READ REQUEST 

FE 

02E8 

1611 


JNE 

LPI040 

NO 

FE 



* 



YES, .PROCESS DC3 OR DC1 

FE 

02EA 

1E0C 


SBZ 

EIARRQ 

CLEAR INPUT INTERRUPT 


02EC 

35C0 

LPI020 

STCR 

R0,7 

GET INTERRUPT REASON 

FE 

02EE 

0240 


ANDI 

R0,>7FFF 

TURN OFF PARITY FLAG 

FE 

02FO 

7FFF 






02F2 

9800 


CB 

R0,a0C3 

IS PRINTER BUSY? 

FE 

02F4 

03B9' 






02F6 

1604 


JNE 

LPI030 

NO. JUMP 

FE 



* 




FE 



* 



SET "RO" DEVICE BUSY BIT. 

FE 

02F8 

E920 


SOC 

aLPFBSY*2+MASTAB, 

aLP0IFF(R4) 

MA 

02FA 

0026+ 






02FC 

0066 






02FE 

1006 


JMP 

LPI040 


FE 


SDSMAC 3.5.0 82.130 16:53:03 FRIDAY, JUN 17, 1983. 

- DNOS LINE PRINTER DSR PAGE 0019 


Figure 5-1 4. DSR Listing Exampie (Sheet 1 1 of 1 6) 


2270510-9701 


5-63 



Writing a DSR 


0872 

0873 

0874 

0875 


0876 

0877 

0878 

0879 

0880 
0881 
0882 

0883 

0884 

0885 

0886 
0887 


0888 

0889 

0890 

0891 

0892 
0903 


0907 


0908 

0909 
OSRLP 
OSRLP 

0921 

0922 

0926 

0927 

0928 

0929 

0930 

0931 

0932 

0933 

0934 

0935 

0936 

0937 

0938 

0939 

0940 

0941 

0942 

0943 

0944 

0945 

0946 

0947 

0948 

0949 

0950 

0951 


S-64 


0300 

9800 

LPI030 

CB 

RO.SDCI A "READY" INTERRUPT ? 

FE 

0302 

03B8' 





0304 

1603 


JNE 

LPI040 NO. JUMP 

FE 



* 


YES. RESET BUSY BIT 

FE 

0306 

4920 


SZC 

aLPFBSY*2■^MASTAB,8LPDIFF(R4) 

MA 

0308 

00264- 





030A 

0066 





030C 

C024 

LPI040 

HOV 

aLP0IFF(R4) ,R0 9902 CONTROLLED ? 

R01 

030E 

0066 





0310 

0A40 


SLA 

R0,aLPF902-*-1 

R01 

0312 

1703 


JNC 

LPI045 -NO. JUMP 

R01 

0314 

1F1B 


TB 

DSR902 -YES. DSR STILL ON? 

R01 

0316 

1306 


JEQ 

LPI050 -YES. JUMP 

R01 

0318 

1002 


JMP 

LPI047 

R01 

031 A 

1F0E 

LPI045 

TB 

EIADSR "DATA SET READY" ON? 

R01 

031 C 

1303 


JEQ 

LPI050 YES. 

FE 



* 


NO. TURN OFF BUSY FLAG 

FE 



★ 


USE "DSR" SIGNAL AS BUSY FE 



* 


INDICATOR. 

FE 

031 E 

4920 

LPI047 

SZC 

aLPFBSY*2-*-MASTAB,aLP0IFF(R4) 

R01 

0320 

0026-t- 





0322 

0066 





0324 

0456 

LPI050 

B 

*R6 

FE 

0326 

C164 

ABORT 

HOV 

aPDTSRB(R4) ,R5 ENDRCD REQUIRED? 

R06 

0328 

005E 





032A 

1306 


JEQ 

ABRT10 -NO. 

R06 



* 


-YES. SET EOR FLAG 


032C 

E920 


SOC 

aLPFE0R*2-)-NASTAB,aLPDIFF(R4) 

R06= 

032E 

002A+ 





0330 

0066 





0332 

E920 


SOC 

aDFG0PF*2■^MASTAB,aPDTFLG(R4) SET OP-FAILED 

R12 

0334 

002C-I- 





0336 

OOOE 





0338 

04C5 

ABRT10 

CLR 

R5 CLEAR COUNT TO BUFFER 

R06 

033A 

0456 


B 

*R6 PROCESS NEXT CHAR 
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033C 

C024 

PWRON 

MOV 

aLPDIFF(R4} ,R0 

DM INTERFACED LP ? 


033E 

0066 






0340 

1107 


JLT 

PURI 

NO 


0342 

1E0F 


SBZ 

DHCIN 

YES, CLEAR INPUT INTERRUPTS 

0344 

1D0E 


SBO 

DMINT 

ENABLE INTERRUPTS 


0346 

1D09 


SBO 

DMVFC 

DISABLE VFC 


0348 

1D07 


SBO 

DMSTR 

INITIALIZE STROBE (ASCII) 


034A 

1D08 


SBO 

DMSTRJ 

INITIALIZE STROBE (JISCII) 


034C 

1024 


JMP 

PUR2 


HA 

034E 

4600 

INIT 

DATA 

>4600 (EIAI 

EN/EIARTS/EIADTR) 


0350 

0A40 

PURI 

SLA 

R0,LPF902-H 

9902 CONTROLLED? 

R01 

0352 

171D 


JNC 

PURI 20 


R01 

0354 

1D1 F 


SBO 

RESET 

RESET THE 9902 CONTROLLER 

R01 

0356 

1F08 


TB 

8 

CONTROLLER EXIST ?? 

R06 

0358 

132C 


JEQ 

NOTBZY 

-NO. 

R06 

035A 

0208 


LI 

R8,CNTL25 

ASSUME A 2.5 MHZ 9902 

RIO 

035C 

A200 






035E 

0209 


LI 

R9,BR25S2 


RIO 

0360 

03BA' 






0362 

1F24 


TB 

CLOCK 

IS THIS A 2.5MHZ 9902 

R06 

0364 

1304 


JEQ 

PUR110 

-YES 


0366 

0208 


LI 

R8,CNTL4 

-NO. 4MHZ. GET CONTROL 

R06 

0368 

AAOO 






036A 

0209 


LI 

R9,BR40S2 

GET BUAD RATE 

R06 

036C 

03E0' 






036E 

3208 

PUR1 10 

LDCR 

R8,8 

OUTPUT CONTROL DATA 

RIO 

0370 

1E0D 


SBZ 

13 

IGNORE INTERVAL DATA 

R02 

0372 

04C8 


CLR 

R8 


R11 

0374 

D224 


MOVB 

aLP0SPX(R4} ,R8 

GET TRANSMIT BAUD CODE 

RIO 

0376 

0076 






0378 

0978 


SRL 

R8,7 

PUT C0DE*2 IN LOU BYTE 

RIO 

037A 

A248 


A 

R8,R9 

INDEX INTO BAUD RATE TABLE 

RIO 

037C 

C259 


MOV 

*R9,R9 

GET CLOCK VALUE 

RIO 

037E 

3009 


LDCR 

R9,0 

SET TRANSMIT BAUD RATE 

R06 
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0952 

0380 

1D26 


S80 

INT902 

ENABLE INTERRUPTS 

R01 

0953 

0382 

1D27 


S80 

ABLTRS 

ENABLE TRANSMITS 

R01 

0954 

0384 

1012 


S80 

RIENB 

ENABLE READ INT FOR RO 

R01 

0955 

0386 

1010 


S80 

RTS902 


R01 

0956 

0388 

1022 


S80 

SECRTS 

SET SECONDARY RTS 

R01 

0957 

038A 

1020 


SOO 

DTR902 

SET OTR 

R01 

0958 

038C 

1004 


JMP 

PWR2 


R01 

0959 

038E 

1009 

PUR120 

S80 

EIADTR 

INITIALIZE EIA INTERFACE 

R01 

0960 

0390 

3020 


LDCR 

SINIT,0 




0392 

034E' 






0961 

0394 

1E0F 


SBZ 

EIAOIM 


FE 

0965 

0396 

C186 

PWR2 

MOV 

R6,R6 

THIS INITIAL POWER UP? 


0966 

0398 

130C 


JEQ 

NOTBZY 



0967 

039A 

0262 


ORI 

R2,>8000//DSFREN 

NO, SET RE-ENTER-ME 



039C 

0400 






0968 

039E 

0380 


RTWP 




0969 



* 





0985 

03A0 

C024 

LPSPUR 

MOV 

8LP0IFF(R4} ,R0 

DM INTERFACED LP ? 



03A2 

0066 






0989 

03A4 

1506 


J6T 

NOTBZY 

YES 

= 

0990 

03A6 

1305 


JEQ 

NOTBZY 

YES 

= 

1000 

03A8 

0A40 


SLA 

RO, LPF902+1 

9902 CONTROLLED ? 

R01 

1001 

03AA 

1702 


JNC 

LPSP05 

-NO. 

R01 

1002 

03AC 

1E13 


SBZ 

XBIENB 

-YES. RESET INTERRUPT 

R01 

1003 

03AE 

1001 


JMP 

NOTBZY 



1004 

0380 

1E08 

LPSP05 

SBZ 

EIAURQ 

EIA RESET INTERRUPT 

R01 

DSRLP 
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DSRLP 

- DNOS LINE PRINTER DSR 

PAGE 

0021 

1005 

0382 

0206 

NOTBZY 

LI 

R6, LPSPUR 

AND IGNORE IT 



0384 

03A0' 






1006 

0386 

0380 


RTWP 




1007 

0388 

11 

DC1 

BYTE 

>11 

READY SIGNAL 


1008 

0389 

13 

DC3 

BYTE 

>13 

BUSY SIGNAL 


1009 


A200 

CNTL25 

EQU 

>A200 

CONTROL REGISTER DATA FOR 

R06 

1010 



* 



9902 


1011 



* 



1 STOP BIT 


1012 



* 



EVEN PARITY 


1013 



* 



CLK4 = 0 .. 2.5 MHz CLK 


1014 



★ 



7-BIT CHARACTER 


1015 


AAOO 

CNTL4 

EQU 

>AA00 

CONTROL REGSISER DATA FOR 

R06 

1016 



* 



A 4MHZ 9902 

R06 

1017 



*********«;*★**★**:****** ********************************* 

RIO 

1018 



* 




RIO 

1019 



* THESE TADLES ARE USED TO CONVERT THE COMMON TRANSMIT 

RIO 

1020 



* AND 

RECEIVE BAUD RATE CODE 

PASSED TO THIS ROUTINE 

RIO 

1021 



* TO i 

SECONDARY CODE FOR SETTING 9902 BAUD RATE. 

RIO 

1022 



* 




RIO 

1023 



* 

9902 

2.5 MHZ BAUD RATE 

TABLE 

RIO 

1024 

038A 

FFFF 

8R25S2 

DATA 

>FFFF 0 

BAUD RATE 50 NOT SUPPORTED 

RIO 

1025 

038C 

0686 


DATA 

>06B6 1 

BAUD RATE 75 

RIO 

1026 

038E 

0509 


DATA 

>0509 2 

BAUD RATE 110 

RIO 

1027 

03C0 

0583 


DATA 

>0583 3 

BAUD RATE 134.5 

RIO 

1028 

03C2 

0558 


DATA 

>055B 4 

BAUD RATE 150 

RIO 

1029 

03C4 

0504 


DATA 

>0504 5 

BAUD RATE 200 

RIO 

1030 

03C6 

04AE 


DATA 

>04AE 6 

BAUD RATE 300 

RIO 

1031 

03C8 

0286 


DATA 

>02B6 7 

BAUD RATE 600 

RIO 

1032 

03CA 

0158 


DATA 

>015B 8 

BAUD RATE 1200 

RIO 

1033 

03CC 

00E7 


DATA 

>00E7 9 

BAUD RATE 1800 

RIO 

1034 

03CE 

OOAE 


DATA 

>00AE A 

BAUD RATE 2400 

RIO 

1035 

03D0 

0074 


DATA 

>0074 B 

BAUD RATE 3600 

RIO 

1036 

0302 

0056 


DATA 

>0056 C 

BAUD RATE 4800 

RIO 

1037 

03D4 

003A 


DATA 

>003A 0 

BAUD RATE 7200 

RIO 

1038 

03D6 

0028 


DATA 

>002B E 

BAUD RATE 9600 

RIO 

1039 

03D8 

0010 


DATA 

>0010 F 

BAUD RATE 14400 

RIO 

1040 

030A 

FFFF 


DATA 

>FFFF 10 

BAUD RATE 19200 

RIO 

1041 

030C 

FFFF 


DATA 

>FFFF 11 

BAUD RATE 28800 

RIO 

1042 

03DE 

FFFF 


DATA 

>FFFF 12 

BAUD RATE 38400 

RIO 

1043 


03E0' 

8R25E2 

EQU 

$ 

MAX TABLE INDEX 

RIO 

DSRLP 


SDSMAC 

3.5.0 
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DSRLP 
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PAGE 

0022 

1045 



* 




RIO 

1046 



* 

9902 

4.0 MHZ BAUD RATE 

TABLE 

RIO 


/ 
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1047 03E0 

FFFF 

BR40S2 

DATA >FFFF 


0 BAUD RATE 50 NOT SUPPORTED RIO 

1048 03E2 

0741 


DATA >0741 


1 BAUD RATE 75 


RIO 

1049 03E4 

0638 


DATA >0638 


2 BAUD RATE 110 


RIO 

1050 03E6 

05D1 


DATA >0501 


3 BAUD RATE 134.5 


R10 

1051 03E8 

05A1 


DATA >05A1 


4 BAUD RATE 150 


RIO 

1052 03EA 

0539 


DATA >0539 


5 BAUD RATE 200 


RIO 

1053 03EC 

0400 


DATA >0400 


6 BAUD RATE 300 


RIO 

1054 03EE 

0341 


DATA >0341 


7 BAUD RATE 600 


RIO 

1055 03F0 

01A1 


DATA >01A1 


8 BAUD RATE 1200 


R10 

1056 03F2 

0116 


DATA >0116 


9 BAUD RATE 1800 


RIO 

1057 03F4 

0000 


DATA >0000 


A BAUD RATE 2400 


R10 

1058 03F6 

008B 


DATA >008B 


B BAUD RATE 3600 


RIO 

1059 03F8 

0068 


DATA >0068 


C BAUD RATE 4800 


RIO 

1060 03FA 

0045 


DATA >0045 


D BAUD RATE 7200 


RIO 

1061 03FC 

0034 


DATA >0034 


E BAUD RATE 9600 


RIO 

1062 03FE 

FFFF 


DATA >FFFF 


F BAUD RATE 14400 


RIO 

1063 0400 

001A 


DATA >001A 


10 BAUD RATE 19200 


RIO 

1064 0402 

FFFF 


DATA >FFFF 


11 BAUD RATE 28800 


RIO 

1065 0404 

0000 


DATA >0000 


12 BAUD RATE 38400 


RIO 

1066 

0406 

' BR40E2 

EQU $ 


MAX TABLE INDEX 


RIO 

1067 


* 





RIO 

1075 



END 





NO ERRORS, 

NO WARNINGS 
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.ABEL VALUE 

DEFN REFERENCES 



PAGE 

0023 

$ 

0406 

1 

0338 0500 

0649 

1043 1066 



ABLTRS 

0027 

0235 

0953 





ABORT 

0326 

0890 

0283 0284 





ABRT10 

0338 

0908 

0891 





BASE 

0022 

0316 

0338 





BR25E2 

03E0 

1043 






BR25S2 

03BA 

1024 

0939 





BR40E2 

0406' 

1066 






BR40S2 

03E0' 

1047 

0943 





BRSTAT R 

0020 

0120 

0311 





C$DN0S 

0004 

A0014 

0004 0417 





CSDPOS 

0004 

A0013 

0028 0041 

0138 

0147 0250 0270 0494 

0545 

0568 




0591 0612 

0625 

0681 0782 0840 0901 

0919 

0963 




0987 





CSOXIO 

0002 

A0011 

0009 0086 

0109 

0122 0160 0287 0411 

0504 

0550 




0574 0596 

0617 

0632 0686 0759 0834 

0894 

0912 




0972 0993 

1069 




C$OS 

0004 

A0019 

0004 0009 

0028 

0041 0086 0109 0122 

0138 

0147 




0160 0250 

0270 

0287 0411 0417 0494 

0504 

0545 




0550 0568 

0574 

0591 0596 0612 0617 

0625 

0632 




0681 0686 

0759 

0782 0834 0840 0894 

0901 

0912 




0919 0963 

0972 

0987 0993 1069 



CLOCK 

0024 

0237 

0940 





CLOSE 

007A' 

' 0384 

0319 





CNTL25 

A200 

1009 

0938 





CNTL4 

AAOO 

1015 

0942 





CR 

0076 

' 0381 






CRLF 

0078 

' 0382 






0C1 

03B8' 

' 1007 

0872 





0C3 

03B9 

' 1008 

0866 





DCD902 

0020 

0226 






OFGOPF 

0005 

C0028 

0907 





OHCIN 

OOOF 

0220 

0846 0926 





DHDHD 

0000 

0218 

0650 





DMINT 

OOOE 

0219 

0927 





DMOUT 

0100 

' 0649 

0628 0629 

0679 

0693 



OMSTR 

0007 

0212 

0671 0673 

0929 




DMSTRJ 

0008 

0213 

0665 0667 

0930 




DNVFC 

0009 

0214 

0928 





DONE 

0158 

' 0514 

0498 





DSCENB 

0015 

0242 

0705 0852 





DSFJAR 

0006 

C0045 

0787 0789 

0796 

0798 



DSFJIS 

0004 

C0043 

0661 0756 





DSFREN 

0005 

C0044 

0967 





DSR902 

001B 

0227 

0702 0879 





DTR902 

0020 

0240 

0957 





DUMP 

013C 

' 0472 

0337 
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EIADCD 

GOOD 

0186 









EIADIM 

OOOF 

0201 

0961 








EIADSR 

OOOE 

0187 

0725 

0882 







EIADTR 

0009 

0195 

0959 








EIAERR 

0009 

0182 









EIAIEN 

OOOE 

0200 









EIANSF 

0000 

0199 

0858 








EIAOUT 

0248* 

0723 

0644 








EIAPAR 

0007 

0193 

0733 

0735 







EIARRQ 

OOOC 

0198 

0860 

0863 







EIARTS 

OOOA 

0196 









EIAWRQ 

OOOB 

0197 

0539 

0542 

1004 






EIAXMT 

0008 

0181 









OSRLP 

SOSMAC 

: 3.5.0 

82.130 16: 

:53:03 

FRIDAY 

JUN 

17. 

1983. 


LABEL 

VALUE 

OEFN 

REFERENCES 






PAGE 0024 

ENDRCD R 

0156' 

0119 

0513 








EXIT 

0144' 

0496 

0455 

0456 

0464 

0465 

0738 




EXIT1 

01 4E' 

0501 

0324 

0325 

0333 

0376 

0441 

0473 



ILLOP 

014E' 

0500 

0317 

0326 

0327 

0328 

0334 

0335 

0336 


INIT 

034E' 

0932 

0960 








INT902 

0026 

0236 

0952 








IRBDBA 

0006 

B0070 

0373 

0392 







IRBICC 

0008 

B0071 

0375 

0454 

0463 






IRBOCC 

OOOA 

B0074 

0374 

0393 

0454 

0458 

0463 

0467 



LPC410 

028E' 

0756 

0749 

0751 

0753 






LPC420 

02AE' 

0796 

0785 








LPC430 

02C2' 

0805 

0757 

0788 

0793 

0797 





LPCOMN 

0274' 

0746 

0709 

0728 







LPDBGN 

0066 

0154 

D0011 








LPDIFF 

0066 

D0012 

0405 

0496 

0501 

0530 

0593 

0627 

0677 

0832 0870 




0875 

0876 

0887 

0903 

0921 

0985 



LPDQCC 

0068 

D0021 

0571 

0584 

0605 

0675 

0715 

0737 

0792 

0801 

LPDQEP 

006E 

D0024 

0547 








LPDQIP 

006A 

D0022 

0558 

0603 







LPDQOP 

006C 

D0023 

0608 

0674 

0692 

0714 

0736 




LPDSPX 

0076 

D0027 

0429 

0947 







LPF902 

0003 

00016 

0406 

0531 

0641 

0849 

0877 

0933 

1000 


LPFBSY 

0002 

D0015 

0700 

0723 

0870 

0875 

0887 




LPFEOR 

0004 

D0017 

0497 

0501 

0593 

0903 





LPFIF 

0000 

D0013 

0419 








LPFUC 

0001 

D0014 

0653 

0748 







LPI010 

02E4' 

0858 

0850 








LPI020 

02EC' 

0864 

0857 








LPI030 

0300' 

0872 

0867 








LPI040 

030C' 

0876 

0854 

0861 

0871 

0873 





LPI045 

031A' 

0882 

0878 








LPI047 

031E' 

0887 

0881 








LPI050 

0324' 

0888 

0880 

0883 







LPn 

02D4' 

0849 

0842 








LPINT 

02C4' 

0831 

0280 








LPSINT 

02CA' 

0832 

0281 








LPSP05 

03B0' 

1004 

1001 








LPSPUR 

03A0' 

0985 

0388 

0604 

1005 






MASTAB 

0022+ 

J0026 

0406 

0419 

0497 

0501 

0593 

0641 

0661 

0700 0723 




0756 

0787 

0796 

0870 

0875 

0887 

0903 

0907 

MAXCOD 

0013 

0338 

0316 








NEWREQ 

0082' 

0388 

0377 








NOTBZY 

03B2' 

1005 

0937 

0966 

0989 

0990 

1003 




OPEN 

007C' 

0385 

0318 








OPNRWD 

0080' 

0387 

0321 








OUT100 

0228' 

0704 

0701 








OUT200 

022E' 

0707 

0703 








OUT410 

0238' 

0711 









OUT902 

021E' 

0700 

0643 








PAGE1 

0072' 

0379 

0308 








PAGE2 

0074' 

0380 









PDTERR 

0042 

C0073 

0472 








PDTFLG 

OOOE 

C0021 

0907 








PDTMC 

0048 

C0077 

0339 

0340 

0341 

0342 

0343 

0353 



PDTRC 

0044 

C0075 

0348 

0349 

0435 






PDTSIZ 

0066 

C0093 

0154 








PDTSRB 

005E 

C0088 

0890 








PDTTM1 

0056 

C0084 

0831 








PDTTM2 

0058 

C0085 

0831 
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POTWC 

DSRLP 

LABEL 

PR9902 

PWR1 

PWR110 

PUR120 

PUR2 

PWRON 

RO 


R1 

R10 

R11 

R12 

R2 

R4 


R5 


R6 


R7 

R8 


R9 


RCOPY 

RDST10 

RDST20 

READST 

RESET 

REWIND 

RFILL 

RFILL1 

RIENB 

RRQ902 

RTS902 

SECOCO 

SECRTS 

STAB 

TST010 

TST020 

TST030 

TST035 

TST040 

TST210 

TST220 

TST230 

TST240 

TST440 

OSRLP 

LABEL 

TST450 

TST480 

TSTDSR 

TSTRR9 

TSTW05 

TSTWR1 

TSTWRQ 

UDFFFF 

WRITE 

XBIENB 

XBRE 
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0046 

C0076 

0350 

0351 

0352 





SDSMAC 

3.5.0 

82.130 

i 16; 

;53:03 

FRIDAY 

, JUN 

17, 1983. 

VALUE 

DEFN 

REFERENCES 






0003 

0252 








0350' 

0933 

0922 







036E' 

0944 

0941 







038E' 

0959 

0934 







0396' 

0965 

0931 

0958 






033C' 

0921 

0282 







0000 


0627 

0641 

0653 

0677 

0700 

0723 

0748 



0864 

0865 

0866 

0872 

0876 

0877 

0921 



1000 







0001 


0373 

0374 

0375 

0392 

0393 

0454 

0454 



0463 

0467 






OOOA 


0310 

0530 

0531 

0547 

0565 

0570 

0571 



0678 

0683 

0707 

0710 

0727 

0729 


OOOB 


0461 

0470 

0496 

0497 

0707 

0710 

0727 

OOOC 


0400 







0002 


0661 

0756 

0787 

0789 

0796 

0798 

0967 

0004 


0405 

0429 

0434 

0472 

0496 

0501 

0530 



0571 

0584 

0593 

0603 

0605 

0608 

0627 



0677 

0692 

0714 

0715 

0736 

0737 

0792 



0831 

0832 

0870 

0875 

0876 

0887 

0890 



0921 

0947 

0985 





0005 


0307 

0374 

0375 

0387 

0405 

0406 

0419 



0436 

0439 

0453 

0459 

0468 

0563 

0563 



0908 







0006 


0388 

0604 

0623 

0746 

0847 

0888 

0909 



1005 







0007 


0308 

0373 

0384 

0385 

0386 

0392 

0457 

0008 


0394 

0396 

0398 

0400 

0402 

0404 

0408 



0429 

0431 

0434 

0435 

0438 

0457 

0466 



0609 

0614 

0652 

0674 

0678 

0683 

0692 



0747 

0791 

0800 

0938 

0942 

0944 

0946 



0949 







0009 


0558 

0565 

0570 

0583 

0603 

0652 

0655 



0660 

0664 

0670 

0711 

0713 

0730 

0731 



0752 

0754 

0784 

0784 

0790 

0799 

0939 



0950 

0950 

0951 





0126' 

0463 

0437 







00C8' 

0409 

0407 







00D2' 

0425 

0420 







008A' 

0392 

0323 







001 F 

0241 

0935 







007E' 

0386 

0320 

0322 

0331 

0332 




0110' 

0454 

0428 

0433 

0440 

0460 

0469 



OIOC 

0453 

0395 

0397 

0399 

0401 

0403 

0425 

0430 

0012 

0245 

0855 

0954 






0010 

0229 

0853 







0010 

0247 

0536 

0955 






0022 

0225 








0022 

0239 

0956 







004E' 

0339 

0310 







0184' 

0565 

0586 







018A' 

0571 

0566 







01A0' 

0603 

0564 

0582 






01B2' 

0608 

0606 







01BC ' 

0623 

0610 







01EA' 

0660 

0654 

0656 

0658 





OIFC 

0670 

0663 







01FE' 

0671 








0204' 

0674 

0668 







0266' 

0735 

0732 







SOSHAC 

3.5.0 

82.130 

1 16; 

!53:03 

FRIDAY 

, JUN 

17. ■ 

1983. 

VALUE 

DEFN 

REFERENCES 






0268' 

0736 

0734 







0270' 

0738 

0537 

0541 

0607 

0651 

0706 

0716 

0724 

0178' 

0547 

0389 

0534 

0623 

0676 




017C' 

0558 








016E' 

0539 

0532 







0176' 

0542 

0540 







015A' 

0530 

0746 







0020+ 

J0024 

0472 







0062' 

0373 

0329 

0330 






0013 

0244 

0535 

0704 

0708 

0851 

1002 



0016 

0228 

0533 








PAGE 0025 


0832 0849 

0933 0985 

0458 0463 

0609 0614 

0729 0805 


0547 0558 

0674 0675 

0801 0831 

0903 0907 

0427 0432 

0585 0890 

0965 0965 

0466 0583 

0424 0426 

0605 0608 

0714 0736 

0947 0948 

0657 0659 

0747 0750 

0943 0949 


PAGE 0026 
0726 
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DNOS Accounting System 


6.1 INTRODUCTION 

At key points while executing each job in the system except the system job, DNOS collects Infor- 
mation about utilization of resources. For Instance, when each task terminates, an entry is logged 
in the accounting file. The entry identifies the task and job under which the task executed and 
includes central processing unit (CPU) utilization and memory allocation data. 

The information is written in a compressed form to one of two accounting files, .S$ACT1 or 
.S$ACT2. The system requires two files. One is being written and the other is available to be pro- 
cessed. The system switches to the other file when the file being written has been filled. If you 
examine these files using the Show File (SF) command, they appear as binary data. The files need 
to be processed by an application program to make use of the data. 

The application program must process the entries in an accounting file before the system fills the 
other accounting file. When one accounting file becomes full, the system accounting routine 
starts to write the other file without determining whether or not the previous contents have been 
processed. 

You must supply the application program to process the accounting file. When the system 
switches files, it bids the application program. This application program can process the data 
directly, copy the information to a magnetic tape, or possibiy advise the operator that the fiie is 
fuii. 


6.2 ACCOUNTING DATA 

Accounting information for all jobs is written to the currently active accounting file in chronologi- 
cal order. The information for each job-related entry includes the job ID. The application program 
can sort the file on the job ID field to organize the information for each job. 

The DNOS accounting file contains six types of entries. The application program must process all 
types of entries as appropriate for the accounting requirements of the site. There is also an identi- 
fication record as record zero of the file; this record must be ignored by the application program. 
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6.2.1 Description of Accumulated Data 

The six entries allowed in a DNOS accounting file are as follows: 

• Job initialization — Contains the account ID, the job name, the job priority, and the user 
ID. 

• Task termination — Contains the task ID, the CPU time used, the fixed priority (based on 
installed priority and job priority), the maximum amount of memory used, the termina- 
tion code, and the number of supervisor calls (SVCs) issued. 

• Job termination — Contains the amount of job communication area (JCA) memory used 
and the amount of JCA memory allocated when the job was created. 

• Spooler device — Contains the job ID, the device name, the device type, and the number 
of I/O requests. 

• User-defined — Supplied by the user task via an SVC. The string from the buffer for the 
SVC is the entry, along with additional information supplied by DNOS. 

• Initial program load (IPL) — Contains the job ID. The IPL entry implies task termination 
for previously active tasks and job termination for previously active jobs. 

Ten bytes of overhead are added to each entry. These bytes contain the type of entry, the number 

of bytes in the entry, the time when the entry was made, priority, and job identification. 

6.2.2 Data Format 

The first ten bytes of all accounting entries contain the following information: 


Dec Hex 


0 

0 

Record Type 

Record Length 

2 

2 

Year/d AY 

4 

4 

Hour 

Minute 

6 

6 

Second 

Priority 

8 

8 

Job id 


2279424 
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Byte Meaning 

0 Record type. Value defines entry, as follows: 

1 — Job initialization 

2 — Task termination 

3 — Job termination 

4 — Spooler device 

5 — User defined 

6 — IPL 

1 Record length, in bytes 

2-3 The year and day. The two least significant digits of the year, in binary 

form, occupy the seven most significant bits. The day of the year (1 - 366) 
in binary form occupies the nine least significant bits. 

4 Hour 

5 Minute 

6 Second 

7 Priority. For a job initialization entry, the job priority. For a task 
termination entry, the initial priority of the task, ignored for other entries. 

8-9 JobID 

The additional bytes of a job initialization entry contain the following information: 

Dec Hex 
10 A 

24 IB 

26 lA 

32 20 

34 22 

40 28 

2279425 
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Byte 

Meaning 

10-25 

Account iD 

26-33 

User iD 

34-41 

Job name 


For a task termination entry, the additionai bytes contain the foiiowing information: 



2279426 


Byte Meaning 

10 Task run-time iD 

11 Task termination code 

12-15 Task CPU time (the count of ciock cycies during task execution) 
16-19 SVC count (the number of SVCs the task issues) 

20 - 23 i/O transfer count (the number of bytes transferred during i/0) 
24 - 25 Maximum memory ailocation, in beets (1 beet = 32 bytes) 
26-29 Eiapsedtime 
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Byte Meaning 

30 Installed task ID 

31 Station number 

32 - 33 Task segment attributes (attributes of segment as installed on program file) 
34 - 41 Task name (as many as eight characters) 

The additional bytes of a job termination entry contain the following information: 


Dec Hex 
!0 A 

12 C 

2279427 

Byte Meaning 

10-11 JCA memory used (number of bytes of JCA used) 

12- 13 Total JCAallocation(numberof bytes of JCA allocated for the job) 
For a spooler device entry, the additional bytes contain the following Information: 


JCA Memory Used 


Total JCA allocation 


Dec 

10 

Hex 

A 

Device Type 

Device Type Flags 

1 2 

C 

Device Name 

14 

E 



16 

10 





Number of i/o Requests 

18 

12 



20 

14 

Time 

Used 


2279428 
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Byte 

Meaning 

10 

Device type flags 

11 

Device type 

12-15 

Device name 

16-19 

Number of I/O requests 

20-21 

Time used (reserved for a count of minutes of use) 


For a user device entry, the additional bytes contain the following user data: 

Dec Hex 

10 A 

n-1 n-1 

2279429 

Byte Meaning 

10 - n User data supplied by the Log Accounting Entry SVC (> 47). This is the entire 
contents of the buffer defined in the SVC block, less the first byte which con- 
tains the byte count. The maximum number of bytes is 70. 

The IPL entry includes only the data in the initial ten bytes. 

6.3 IMPLEMENTATION 

To implement the accounting subsystem, you must do the following: 

• Define account numbers. 

• Generate a system that includes the accounting subsystem. 

• Provide a task to process the accounting information. 
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6.3.1 Account Numbers 

Account numbers are user-defined character strings 16 bytes in iength. DNOS does not impose 
any other restrictions. 

Account verification is optionai and requires a file of valid account numbers. The name of this file 
must be .SSACCVAL. This file must be a sequential file with one account number per record. Be 
sure to include a blank record in the file If any users can log on without an account number. With- 
out this blank record, all jobs in the system must use an account number listed in the file. Write 
the file of valid account numbers to provide account verification. When file .SSACCVAL has not 
been created, account numbers are not validated. 

6.3.2 System Generation Requirements 

The accounting subsystem is an option that can be included when a DNOS system is generated. A 
group of SVCs (the accounting group) consists of the two SVCs required to support job account- 
ing. By including the accounting group of SVCs, you implicitly request that the accounting sub- 
system be included. Nothing else is required to generate a system that supports job accounting. 

6.3.3 Appiication Program Requirements 

The third requirement for job accounting is an application program to retrieve and process the 
information on the accounting file. This task must be installed on the system utilities program file 
.S$UTIL as task ID > 54, which is reserved for the user accounting task. When an accounting file is 
full, DNOS starts the task installed at ID >54. 

The application program can determine the file that needs processing by issuing a Get Task 
Parameters SVC. The third byte of the task parameters contains a 1 in ASCII form if the first file 
needs processing and a 2 in ASCII form if the second file needs processing. If the processing task 
is written in Pascal, it must be linked with the MINOBJ routine so that stack and heap parameters 
are not expected as task bid parameters. 

Processing the entries on one file while the other file is being written, the application program can 
copy the entries to a more permanent file to be processed offline or at a later time. 
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7.1 INTRODUCTION 

In a DNOS system using file security, a user can perform an operation on a flie oniy if the foliowing 
two conditions are met: 

• You are a member of an access group that has access rights to the file. 

• The operation is allowed by the access rights that the access group has to the file. 

You should refer to the DNOS System Command Interpreter (SCI) Reference Manual for explana- 
tions concerning any commands with which you are not familiar. Read this entire section before 
you attempt to use file security. If you have any questions concerning file security, talk to the 
security manager of your system. 


7.2 ACCESS GROUPS 

An access group is composed of a set of user IDs. The users of these IDs usually have a common 
work assignment or a common need for system resources. 

The name of an access group must be a string of one to eight alphanumeric characters, with the 
first character alphabetic. Access rights to particular files on the system are assigned by access 
group name. Each secured file on the system can have access rights defined for up to nine access 
groups. You can define a different set of rights for each group. 

There are two types of access groups: pre-defined and user-defined. PUBLIC and SYSMGR are the 
only two predefined access groups. 

Everyone on the system is automatically an access group member of PUBLIC. A user who belongs 
only to the PUBLIC access group has rights only to unsecured files and files that creators have 
defined for PUBLIC access. 

Usually, only the security manager or a small, trusted group belongs to the SYSMGR access 
group. The SYSMGR group has access rights to every file and implied leadership of every access 
group. 

All other access groups on the system are user-defined and are created for a specific purpose. The 
creator of an access group automatically becomes the initial access group leader. The leader des- 
ignates which users on the system are members of his access group. A user can be a leader of one 
or more access groups and also a member In others. 
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After creating a file, a user can specify which access groups are allowed access to it and the types 
of access these groups can have. 

The roles one can play in access groups are briefly described in the following paragraphs. 

7.2.1 SYSMGR Access Group Member 

Because a member of the SYSMGR access group can access every file in the system and assume 
leadership for every access group, this group is not to be used for routine tasks. The SYSMGR 
access group should be limited to three special functions: 

• Setting up the security environment 

• Solving of unusual system problems 

• Applying patches supplied by Texas Instruments 

The security manager is normally either the only member of SYSMGR or the leader of a small, 
trusted group. 

7.2.2 Access Group Leader 

A user on the system becomes an access group leader either by creating an access group or by 
having the leader of an access group give up his leadership and designate him as the new leader. 

Each access group has only one leader (however, any member of the SYSMGR access group can 
perform any function the leader can). The access group leader controls membership In the group 
by his right to add or delete members. To create an access group, a user must have access to the 
Create Access Group (CAG) command procedure. User IDs associated with the SYSMGR access 
group cannot be used with the CAG command. 

7.2.3 Access Group Member 

An access group member is a person whose user ID belongs to the set of user IDs for a specific 
access group. Only the access group leader (and members of the SYSMGR access group) can add 
or delete access group members. An access group member shares the access rights of his group 
to files on the system. Every user is a member of at least one access group since all users of the 
system belong to PUBLIC. 

7.2.4 Creation Access Group 

A user’s creation access group is the access group that has all access rights to files he creates. 
Every user on the system has exactly one creation access group. A user must select one of the 
access groups to which he belongs as his creation access group. A user makes this selection by 
executing the Set Creation Access Group (SCAG) command. If a user never specifies a particular 
group, his creation access group is PUBLIC by default. 

As long as the creation access group retains control access, only users who belong to the group 
(or members of SYSMGR) can give any access rights to a file to other access groups (by executing 
the Modify Security Access Rights (MSAR) command). Giving read, write, execute, or delete 
access rights to another group does not take away these rights from a user’s own group. However, 
since only one access group can have control access to a file, giving control access to another 
access group means taking it away from the user’s group. Therefore, a user should be very careful 
before assigning control access for a file to another access group. 
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For example, a user selects an access group called LAWYERS as his creation access group. He 
logs off and logs on again (the system recognizes the selection only in this manner). Then, he cre- 
ates a file called ACCOUNTS. The LAWYERS access group now has control, read, write, execute, 
and delete access to ACCOUNTS. Later, he decides that a related access group, called 
PARALGLS should have read access and write access to the file. He would then use the MSAR 
command to assign them these two rights. Later, unknown to him, a junior member of LAWYERS 
uses the MSAR command to assign control access to the PARALGLS access group. The next time 
he tries to assign access rights to ACCOUNTS with the MSAR command, he will receive an error, 
since his access group, LAWYERS, no longer has control access to the file. After locating and tak- 
ing appropriate revenge on the junior member of LAWYERS who gave the file away, he would have 
to talk one of the members of PARALGLS (or a member of SYSMGR) into using the MSAR 
command to return control access to LAWYERS. 

7.2.5 Modifications to Access Groups and Access Rights 

The system determines what access groups a user belongs to when a job is created with that 
user’s ID. Therefore, for the system to recognize any selection or modification that involves 
access groups, the user affected by such a change must log off and then log back on again for the 
change to take place. Changes to membership in an access group or to the selection of current 
creation access group do not affect running jobs. 

Modifications to the access rights of a file take effect immediately. However, the system deter- 
mines a user’s access rights to a file when he tries to assign a LUNG to the file. Therefore, if a 
LUNG is already assigned to a file in a job, the job will execute regardless of any changes to the 
file’s security. 

For example, you are running a job that uses a file to which your access has all access rights. If 
someone uses the Modify Security Access Rights (MSAR) command to take away all the access 
rights to the file, the job you are running may or may not be affected. If a LUNG is aiready assigned 
to the file, the modification will not affect the running job. However, if the LUNG has not been 
assigned, an error occurs when the task (under which the job is running) tries to access the file for 
which you no longer have access rights. 


7.3 ACCESS RIGHTS 

There are five possible types of access rights to a file: 

• Control access 

• Read access 

• Write access 

• Execute access 

• Delete access 

The access rights that an access group possesses define the ways in which its members can use 
a particular file. 
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Only one access group can have control access to a file. However, a member of an access group 
that has control access to a particular file can give any access group any combination of the first 
four rights to the file. 

You can use the MSAR command to assign or alter access rights to a file. When securing a file, 
you should carefully consider security requirements before deciding which groups should have 
access rights to the file. You should consider whether or not certain access rights can be withheld 
without affecting the normal work of the users. The following paragraphs describe each of the 
access rights. 

7.3.1 Control Access 

Controi access is the right to change the access groups associated with a file or to change the 
access rights of any access group. Oniy one access group can have controi access to a particular 
file. You must be part of an access group that has control access to a file in order to execute the 
MSAR command on that file. 

7.3.2 Read Access 

Read access is the right to read the contents of a file. This right also enables you to execute a file 
if it is an SCI batch stream or command procedure. If the file is a program file, read access allows 
you to designate the file when issuing the Map Program File (MPF) and Show Program Image (SPI) 
commands. With read access to a file, you can copy the contents of the file into any file for which 
you have write access. 

7.3.3 Write Access 

Write access is the ability to write data into a file. It allows you to modify old data and write new 
data. In addition, write access to a program file enables you to install or delete tasks, segments, 
procedures, and overlays. If the file is a key indexed file, this right allows you to Insert or delete 
records from the file. 

7.3.4 Execute Access 

Execute access applies only to program files. This right allows you to execute tasks, segments, 
procedures, and overlays within a program file. As a security measure, you can protect your pow- 
erful or sensitive tasks by placing them in a protected program file. However, do not move tasks 
supplied by Texas Instruments, as this step would affect the ability of the system to accept Texas 
Instruments patches. 

7.3.5 Delete Access 

Delete access is the right to delete (or replace) a file. In order to text edit a file, you must have both 
write and delete access. 


7.4 EXAMPLE OF A SECURED SYSTEM 

Figure 7-1 shows the relationship between access groups and access rights to particular files. 
Imagine a system that currently has only two user-defined access groups (ADMIN and FINANCE) 
and two secured files (ACCOUNTS, and BILLING). PRES is the access group leader for ADMIN. He 
has designated ADMIN as his creation access group. 
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ACCESS GROUP 


IDS OF MEMBERS 


ADMIN PRES , VP 

FINANCE CMPTRLR , ANALYST , CLERK I , CLERK2 


secured file access group access RIGHTS 


ACCOUNTS 

ADMIN 

READ , 

DELETE , CONTROL 


FINANCE 

READ . 

WRITE 

BILLING 

ADMIN 

READ , 

WRITE, delete, CONTROL 


FINANCE 

READ 



2284929 


Figure 7-1. Access Groups and Secured Files 


In this system, PRES can read both of the secured files because read access to these files has 
been defined for the ADMIN access group. He can also write to the BILLING file. ANALYST can 
write to ACCOUNTS because write access to the file has been defined for the FINANCE access 
group. However, if he tries to write to the BILLING file, he will receive an error because write 
access has not been defined for his access group. 

Consider that PRES needs to modify the accounts that his company has. To do so, he must estab- 
lish write access to the ACCOUNTS file. Because he belongs to the ADMIN access group (which 
has control access to that file), he may issue the MSAR command to give write access to ADMIN. 

Consider that ANALYST was convinced he could help ADMIN modify the BILLING file. He has two 
options. First, he could ask PRES (the access group leader) to include his user ID in the ADMIN 
access group. Second, he could ask anyone in the ADMIN access group to modify the security of 
the file In order to give write access to his access group, FINANCE. 
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Consider that PRES wants to create a stock strategy file which only the PRES, VP, and CMPTRLR 
can access. He can create an access group cailed LEADERS by executing the CAG command. 
PRES automaticaily becomes access group ieader of LEADERS because he executed the com- 
mand. If he wants to designate someone else as the leader he must execute the Modify Access 
Group (MAG) command. Then, he can use the Create File (CF) command to create a file named 
STRATEGY. The ADMIN group now has all access rights to the file (because PRES has selected 
ADMIN as his creation access group). He can then execute the MSAR command to define what 
access rights he wants the LEADERS access group to have. 

After these operations, the system would have one additional access group and one additional 
secured file, which might appear as follows: 


ACCESS GROUP 


IDS OF MEMBERS 


LEADERS 


PRES, VP, CMPTRLR 


SECURED FILE ACCESS GROUP 


ACCESS rights 


STRATEGY ADMIN 

LEADERS 


READ, WRITE, DELETE, CONTROL 
READ , WRITE 


2284930 


Figure 7-2. Creating an Access Group 


7-6 


2270510-9701 



File Security 


7.5 IMPORTANT POINTS ABOUT ACCESS RIGHTS TO SECURED FILES 

Each secured file can have access rights defined for up to nine access groups. The MSAR com- 
mand assigns access rights and modifies them. You can define a different set of rights for each 
group. 

The rights granted to an access group define the rights of each member. The rights of an individual 
user are determined by membership in access groups. A user can access a file only if he is part of 
an access group that has rights to the file. 

The rights to a file for a given user are a composite of the rights for all of the access groups to 
which he belongs. For example, a user is a member of two access groups. The first has read 
access to a file and the second has write access to the same file. In this case, the user has both 
read and write access to that file. 

Access rights are independent of each other. Any combination of rights can be assigned to a file, 
even if certain combinations would not appear to make much logical sense. 

The system establishes what access groups a user belongs to when a job is created with that 
user’s ID. 

The system establishes a user’s access rights to a file when he assigns a LUNO to the file. 

The write-protect, delete-protect mechanisms of the Modify File Protection (MFP) are independent 
of file security, except in one way. To use the MFP command on a file, you must have write access 
and delete access. 

Changing the data in a file or the name of a file does not affect the access rights associated with 
the file. However, if you delete a file and create a new one with the same name, the file is no differ- 
ent from any other that you create under your user ID: your creation access group Inherits all 
access rights to the new file. 

Programs that copy files normally read the data from an input file and write the data to an output 
file. If the copying process is executed with any of the following SCI commands, the security 
rights of the input file are transferred to the output file: 

• BDD— Back Up Directory to Device (followed by the Restore Directory (RD) command) 

• CV— Copy Volume 

• CVD— Copy Volume to Device 

• DCOPY— Disk Copy/Restore 

If the copying process is executed with any other command, the security of the input file Is not 
transferred to the output file. 
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7.6 PROGRAMMERS 

The following facilities related to security are available to programmers: 

• I/O utility operations that specify a user ID 

• Tasks designated as security bypass tasks 

• Special Rename File SVC option 

• Open routine specifying user ID (S$OPNS) 

• No echo option for SCI prompt response 

• Read file characteristics security option 
7.6.1 I/O Utility Operations That Specify a User I D 

In most cases, when a task uses a file, it does so with the access rights of the user ID of the job in 
which it is running. In other cases, the task may be a special request server that runs in its own 
job. In the latter case, the task may need to access a file with the access rights of the requesting 
task. The user ID and passcode of the requesting task are specified as an I/O parameter in the 
Supervisor Call (SVC) block for I/O utility operations in the request server task. For security bypass 
tasks, the passcode does not need to be specified. A security bypass task that specifies a user ID 
in the parameter list does not bypass security checking for the specified i/0 operation. Instead, it 
picks up the access rights associated with the specified user ID. To set up an SVC block that spec- 
ifies a user ID, refer to the DNOS Supervisor Call (SVC) Reference Manual. 

The following I/O utility operations may specify a user ID as an SVC block parameter: 

• Assign LUNO— This operation assigns a LUNO if the specified user has any access 
rights to the file. All subsequent I/O operations that use the LUNO are verified against 
the specified user’s access rights. 

• Create File— This operation creates a file with full access rights given to the creation 
access group of the specified user. 

• Delete File— This operation deletes a file if the specified user ID has delete access to 
the file. 

• Unprotect File— This operation removes write and delete protection from a file if the 
specified user ID has write and delete access to the file. 

• Write Protect File— This operation write protects a file if the specified user ID has write 
and delete access to the file. 

• Delete Protect File- This operation delete protects a file if the specified user ID has 
write and delete access to the file. 
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7.6.2 Security Bypass 

Security bypass gives access rights to a program without giving it to the user. The Modify Task 
Security Attribute (MTSA) command assigns security bypass to a task in a program file; it can also 
remove this privilege. 

A task that is installed with the security bypass attribute is granted access to any file on the sys- 
tem (except any task that uses an I/O utility operation specifying user ID). For this reason, you 
should secure the MTSA command under your security manager maintenance access group, so no 
one but you can assign the security bypass attribute to a task. It is your responsibility to guarantee 
the integrity of the task, as the task itself must enforce security. You, or a trusted programmer, 
should look over the logic of the task to insure that no unnecessary files are accessed. Once you 
have approved the task, you should perform the following steps: 

1 . Assign the security bypass attribute to the task with the MTSA command. 

2. Use the MSAR command to give the control, delete, and write access rights for the pro- 
gram file to your security manager maintenance group. With read and execute access, 
the user can use the program file for the needed purpose but he does not have the ability 
to modify it. 

3. Write protect the program file for the task, so the file cannot be modified. 

A security bypass task that uses one of the I/O utility operations that specify user ID is affected as 
follows: 


• The task inherits the access rights of the user ID specified rather than the full access 
rights normally given to a security bypass task. 

• The task does not need to specify the user passcode in the SVC parameter list. 

To set up an SVC block for I/O utility operations that specify user ID, refer to the DNOS Supervisor 
Call (SVC) Reference Manual. Having a security bypass task use one of these operations is useful 
in cases where you want to give a task unlimited access to files during execution but you want 
normal file access security for input and output files. 

For example, you are willing to give the security bypass attribute to a user’s task but you want to 
guarantee that he can only place the output from the task into files for which the user has access 
rights. You can limit the user in this way by having the task use an Assign LUNC SVC that speci- 
fies his user ID when the task attempts to place the output in a specified file. At this point, the task 
loses its security bypass attribute. Therefore, before assigning the LUNC, the system checks 
whether the user has the proper access rights to the output file. 

7.6.3 Special Rename File SVC Option 

With the normal execution of the Rename File SVC, the new file assumes the security of the old 
file. For example, if you are modifying a file called LIST1 to be called LIST2, the LIST2 file assumes 
the security that belonged to LIST 1 . 

However, the special Rename File option allows you to keep the security of the destination file (if 
It exists) rather than that of the source file. Refer to the DNOS Supervisor Call (SVC) Reference 
Manual for details about this option. 
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You can use the option under the following three conditions: 

• The destination file already exists. 

• The replace option is specified. 

• You have write access to both the source fiie and the destination fiie. 

7.6.4 Open Routine Specifying User iD (S$OPNS) 

The S$OPNS routine performs the following functions: 

• Executes an Assign LUNO SVC, specifying a user ID. 

• Opens a user-specified file, a user-specified device, or the Terminal Local File (TLF) for 
write access. To perform the S$OPNS routine, refer to the DNOS Systems Programmer’s 
Guide. 

A programmer should use this routine instead of the standard S$OPEN routine when the following 
conditions are true: 

• The calling task is a security bypass task. 

• A standard security check on the listing file is desired. Therefore, a user who executes 
the task cannot place the output in a file for which he does not have access. 

7.6.5 No-Echo Option for SCI Prompt Response 

When writing SCI prompts, a programmer can use the no-echo option to indicate that data entered 
into a field is not to be displayed. Refer to the DNOS System Command Interpreter (SCI) Reference 
/Ifanua/ for details. 

7.6.6 Read File Characteristics Option 

The Read File Characteristics operation of the i/0 SVC has an option that ailows the issuer of the 
SVC to determine what rights he has to a file. If the option is specified, the SVC returns a word of 
data in the specified buffer. The data indicates what access rights the issuer of the SVC has to the 
file. 

The issuer of the SVC can aiso determine what access rights another user has to a file. If the user 
has access rights, he has previously been assigned a LUNO that specified his user iD. The issuer 
of the SVC can use this LUNO to find out what access rights the user has. 

Refer to the DNOS Supervisor Call (SVC) Reference Manual for detaiis about this option. 
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8.1 SYSTEM INITIALIZATION PROBLEMS 

During the initial program load (IPL) process, the system crashes when a loader error is encoun- 
tered. The three loaders used to load the DNOS operating system Into memory are the read-only 
memory (ROM) loader, the program image loader, and the system loader. The following para- 
graphs discuss the error indications provided by the three loaders. 

8.1.1 ROM Loader Errors 

When an error occurs during ROM loader execution (TILINE load), the system crashes. The most 
common errors are controller and unit select errors. Regardless of the type of error, the fault light 
flashes on and off to indicate an error occurred. Depending on the error, the status of TILINE 
peripheral control space is displayed on the Indicators of the programmer panel. 

If the error is a controller error and you are using a 990/10 or 990/12 computer, one of the following 
indicators lights up on the front panel: 


0 6 

7 

8 

9 

1 0 

1 1 

f 2 

1 3 

14 

15 

Always Zeros 

AC 

ME 

DE 

TT 

IE 

RE 

CT 

SE 

0 


2279430 


AC — Abnormal completion IE — ID error 

ME — Memory error RE — Rate error 

DE — Data error CT — Command timer 

TT — TILINE time-out SE — Seek error 

Refer to the appropriate disk installation and operation manual for further information regarding 
error conditions. 

If the error is a unit error and you are using a 990/10 or 990/12 computer, the following status word 
appears on the indicators: 


0 

1 

2 

3 

4 

5 

6 

15 

OL 

NR 

WP 

US 

0 

SI 

Unknown 


2279431 
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OL — Offline US — Unsafe 

NR — Not ready SI — Seek incomplete 

WP — Write protect 

8.1.2 Program Image Loader Errors 

When the program image loader detects an error, it terminates with the flash crash routine. This 
routine displays > FF in the leftmost indicators, flashing on and off. The rightmost indicators 
show either of the following error codes: 

> 01 — Error loading from the disk 

> 08 — Unable to locate loader file 

If the >01 error is displayed, disk track 1 information may have been destroyed. If the >08 error is 
displayed, either an invalid system loader file name has been specified in the volume information 
or the disk image of the system loader file is damaged. 

8.1.3 System Loader Errors 

When the DNOS system loader detects an error during the IPL, the way it reports the error to you 
depends on what kind of computer you are using. On a 990/10 or 990/12 system, the loader dis- 
plays the error code in the rightmost seven indicators and the phase number in the leftmost nine 
Indicators on the programmer panel. The phase number indicates the last successful phase exe- 
cuted, indicating that the loader detected an error in the next phase. The leftmost nine indicators 
flash on and off to indicate that the error occurred In the system loader. On a Business System 
computer, the hexadecimal equivalent of the error code Is displayed in four digits on the front 
panel. 

Figure 8-1 shows the programmer panel phase number and error code display on a 990/10 or 
990/12 computer. The phase number is displayed as a bar graph starting from the leftmost indica- 
tor. Indicator 0 is lit at the completion of phase 1, indicator 1 is lit at completion of phase 2, and so 
on. Each indicator remains lit until the loader completes execution. 

On a Business System Computer, the hexidecimal equivalent of the error code is displayed in four 
digits on the front panel. Table 8-1 lists the phase numbers. The error code is displayed as a binary 
number. Table 8-2 lists the codes and their meanings. 


Phase Number 


Error code 


2279432 


Figure 8-1. System Loader Error 
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Table 8-1. System Loader Phases 


Indicator 

Phase 

Description 

0 

1 

Successful loader relocation 

1 

2 

Successful open of kernel program file 

2 

3 

Successful load of writable control store (WCS), load of 



system root, and verification of system version 

3 

4 

Successful loading of special table areas 

4 

5 

Successful initialization of system overlay table and crash file 

5 

6 

Successful loading of JCA segments 

6 

7 

Successful loading of DSRs and scheduler 

7 

8 

Successful loading of memory-resident system tasks 

8 

9 

Successful loading of user memory-resident tasks 


Table 8-2. System Loader (Flashing) Crash Codes 

Error Code 

Description 

>01 

Load device I/O error 

>02 

Not enough memory to load system 

>03 

System disk not found in image file 

>04 

Error in program file directory 

>05 

Loader incompatible with system version being loaded 

>06 

Disk bit map error 

>08 

No system loader file 

>09 

No kernel program file 

>0A 

System segment not found in program file 

>0B 

No patches applied to system 

>0C 

Software version too old 

>0D 

No utility program file 

>0E 

No swap file 

>0F 

Kernel program file revision is inconsistent with file revision 

>11 

Unable to get system table area 

>13 

Logical address space overflow 

>14 

Unable to load WCS file 

>60->6F 

Error interrupt (Level 2) 

>68 

Insufficient user task area 


Refer to the DNOS Messages and Codes Reference Manual for more diagnostic information on 
loader f iash crashes. 
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8.2 SYSTEM CRASH PROBLEMS 

When DNOS detects a system failure, it displays an error code on the front panel indicators and 
places the CPU In the idle mode. The fault indicator also lights to indicate a system crash. At this 
point, all the terminals stop responding to users. 

To analyze the system crash, perform the following steps: 

1. Press HALT and then RUN on the front panel to copy the contents of memory to the 
predefined crash file on disk. 

2. Perform the IPL to load the system again. 

3. Bid SCI at a terminal. 

4. Enter the XANAL command to execute the crash analyzer. 

To perform the IPL, press HALT and LOAD on the front panel. Refer to the DNOS Operations Guide 
for the complete procedures. 

The Execute Crash Analysis Utility (XANAL) SCI command provides a formatted listing of the sys- 
tem crash file. A systems programmer can use this listing to analyze the cause of the system 
crash. 

The commands given to XANAL select portions of the memory dump on the crash file (or actual 
memory if the running system is being analyzed) and write them to the listing device in a formatted 
form. Table 8-3 summarizes the XANAL commands. 
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Table 8’3. XANAL Commands 


Command 

Action 

ALL 

Execute all of the commands 

AQ 

Display contents of active queue 

CCB 

Channel control block 

DM 

Dump a specific area of memory 

FCB 

Dump file control blocks 

Gl 

Display general information 

JSB 

Dump job status blocks (JSBs) 

LDT 

Logical device tables 

MM 

Memory maps 

OVB 

Overhead beets 

PBM 

Partial bit maps 

PDT 

Dump physical device tables 

PQ 

Display all other system queues 

QU 

Terminate session 

ROB 

Resource ownership blocks 

RPB 

Resource privilege blocks 

SGB 

Dump segment group blocks 

SSB 

Dump segment status blocks 

ST 

Dump secondary table areas 

TA 

Dump task areas currently in memory 

TR 

Dump registers for all tasks 

TS 

Display task status 

TSB 

Dump task status blocks (TSBs) 

?? 

List ail commands 


Normally, you should execute the Gl, TS, and JSB commands in sequence to obtain the general 
information about a crash. The programmer can then print some of the data structures (such as 
TSBs) and memory maps as needed. The data structures printed by XANAL are described in detail 
in the DNOS System Design Document. 

Sometimes a great deal of knowledge about the system and system data structures is required to 
determine the underlying causes of the system crash from the XANAL listing. However, a systems 
programmer should be able to get much general Information from the crash dump without getting 
involved In the details of the system structures. 

If you cannot resolve a system crash, do the following: 

• Report the system crash to a customer representative. 

• Provide a copy of the crash file (.S$CRASH) on a magnetic medium to the customer 
representative. (The medium will be returned after the data has been copied from It.) 

• Also provide the three link maps of the system and a file describing the events that led 
to the crash. 
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8.2.1 Organization of the XANAL Listing 

The first page of the crash dump generated by the Gi command contains the general information 
block. Figure 8-2 shows an example of general information printed by the XANAL utility. The fol- 
lowing paragraphs briefly describe each entry of the XANAL listing shown in Figure 8-2. 

8.2.1. 1 Crash Code. The first entry is the system crash code displayed on the front panel when 
the crash occurred and the meaning of that code. An example of the crash code display is as 
follows: 

CRASH CODE = 00A2 FILMGR -- INCONSISTENT STRUCTURE 

In this example, > A2 (leading zeros are omitted in this section) was the error code returned when 
file management detected an inconsistent data structure. 

If the crash code is in the range of >60 through >6F (referred to as >6x crash), the crash code 
represents a level 2 interrupt error. An example of the crash code for a > 6x crash is as follows: 

CRASH CODE = 0062 ERROR IN OS - ILLEGAL INSTRUCTION 
/ \ 

/ \ 

CRASH TYPE ERROR CODE 

The third digit identifies a > 6x crash and the last digit describes the cause of the crash. 

8.2.1 .2 Executing Task. The second entry is the address of the TSB of the task that was execut- 
ing when the crash occurred. When this value is 0, no task was executing at the time of the crash. 
Therefore, the crash occurred within the operating system, probably during a scheduling cycle. 

8.2.1.3 Executing Task JSB. The third entry is the address of the job JSB of the task that was 
executing when the crash occurred. The JSB contains the job name, job ID, and user ID of the job. 

8.2.1.4 Location of Failure. This entry is the address from which the crash routine was called. 
In some cases, this entry points to the exact location of the crash. However, in most cases, this 
value is the location of a common crash point that can be entered from any of several locations. 

8.2.1.5 Status Register. This entry lists the value of the status register when the crash 
occurred. The last four bits (last digit in the entry) of the status register are the interrupt mask. The 
status register information Is valuable when the crash code is in the range of > 10 through > IF, 
indicating an illegal Interrupt. When an illegal interrupt occurs, the interrupt mask value Is in the 
range of > 2 through > E (refer to the paragraph on forcing a system crash). When the crash code is 
>6x, the Interrupt mask value Is 1. This value Indicates that the crash was caused by one of the 
task error states occurring within the system or within a system task. 

8.2.1.6 CURMAP Addr. This entry lists the value of the current map file at the time of the crash. 
This information Is useful when the crash code Is > 61 (memory parity error). You can calculate the 
physical memory location using this information If the failure is in map 0. If the failure is in map 1, 
use the values of the map registers in the TSB. 
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SYSTEM DUMP ON 8/15/81 AT 10:17 — VERSION 1.2.00 


CRASH CODE = 0062 ERROR IN OS - ILLEGAL INSTRUCTION 
EXECUTING TASK = 0000 
EXECUTING TASK USB = 0000 ’ 

LOCATION OF FAILURE = 0E92 

STATUS REGISTER AT TIME OF FAILURE = C401 

JCASTR=9000 

COUNTRY CODE =UNITED STATES 
IMAGE NAME= S^tSHIP 
MEMORY SIZE 756K BYTES 

CRASH FILE SIZE 756K BYTES 
CURMAP ADDR = 4622 

EXECUTING WORKSPACE AT TIME OF DUMP 
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0000 

FFFF 
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OOOF 

OOOF 

0000 

0000 
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Figure 8-2. General Information Block 
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8.2.1.7 System Patch Area. This entry lists patches that have been applied to the system. Use 
this information to verify that all out-of-line patches have been applied to the system successfully. 
The beginning address of the patch area should be equal to the value assigned to NFPATCH. 
Examine the SYSMAP listing for your system to see the expected address. The last few lines of the 
patch area show the revision level of the release. Check the revision level to make sure that all 
recent patches have been applied. The patches are applied at the end of system generation. 

8.2.1. 8 Executing Workspace at Time of Dump. The executing workspace contains the regis- 
ters of the executing code at the time of the crash. 

8.2.1. 9 Hardware Trap and Extended Operation (XOP) Vectors. Exmine the transfer vectors for 
hardware Interrupts and XOPs to verify that they are intact. Since these values reside in the first 64 
words of physical memory, they can be destroyed by a system task that branches to memory loca- 
tion 0. Usually, the locations that are destroyed are locations >0 through >3 (power-up interrupt) 
or locations > 1 A through > 1 F. Locations > 1 A through > 1 F are destroyed when a task executes a 
BLWP instruction to location 0. When the BLWP Instruction is executed, the return context infor- 
mation of the calling task is stored In locations > 1 A through > 1 F. When a > 6x crash occurs and 
the interrupt mask in register 15 of the workspace for interrupt level 2 indicates a defined interrupt 
(mask value minus 1), check the interrupt trap values to determine if they are within the proper 
address range. Except for interrupt levels 0, 1, 2, and 5, the workspace pointer and program 
counter for each interrupt level should contain addresses that are relatively close to each other. 

8.2.1.10 Special Workspaces. The workspaces for the clock processor, the level 2 interrupt 
processor, and the SVC processor are printed last. These routines are entered through context 
switches and the return context is found in registers R13, R14, and R15 of these workspaces. 

If the crash code is >6x, XANAL prints out the active workspace at the time of the crash and 16 
words of locations around the address in the program counter at the time of the interrupt. 

The clock workspace contains the location in the executing task where the last clock interrupt 
occurred. The SVC workspace contains the location of the last SVC or the scheduling location. 
These two locations can sometimes help to determine where a task was executing at the time of 
the crash. The interrupt 2 workspace contains diagnostic information about a >6x crash. R13 
through R15 contain the context of the crash within the system. 

When looking at the saved status register for Interrupt 2 (R15), notice the value of bit 8. If bit 8 is 
set to 1, the crash occurred In task code (map 1). If bit 8 is set to 0, the crash occurred in system 
code (map 0). 

8.2.2 Task States and JSBs 

The TS and JSB commands list the task states and JSBs of all tasks in memory at the time of the 
crash. Figure 8-3 shows example lists of task states and JSBs. 
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TASK STATES 


TASK NAME 

ID 

WP 

PC 

ST 

STATE 

FLAGS 

STATION 

TSBADR 

JSB ADR 

PROG FILE 

filemgr 

0502 

90A4 

COSA 

209F 

0005 

F320 


91F4 

71A4 

S$SHIP 

3YNC0B 

0301 

6CE4 

476A 

C5CF 

DE04 

OCOO 

9 

9152 

71A4 

PROG 

filemgr 

0502 

90A4 

COSA 

209F 

0005 

F320 


91F4 

717A 

SSSHIP 

SYNC OB 

0301 

6CE4 

476A 

C5CF 

DE04 

OCOO 

8 

9152 

717A 

PROG 

filemgr 

0502 

90A4 

COSA 

209F 

0005 

F320 


91F4 

7126 

SSSHIP 

SYNCOB 

0301 

6CE4 

476A 

C5CF 

DE04 

OCOO 

6 

9152 

7126 

PROG 

filemgr 

0502 

90A4 

COSA 

209F 

0005 

F320 


91F4 

70FC 

SSSHIP 

SYNCOB 

0301 

6CE4 

476A 

C5CF 

DE04 

OCOO 

5 

9152 

70FC 

PROG 

RPRCP 

4C13 

E27E 

E25E 

209F 

0004 

C520 


9410 

6F88 

S^UTIL 

FILEMGR 

0502 

90A4 

C04C 

249F 

0024 

F320 


91F4 

6F8e 

SitSHIP 

SC I 990 

0101 

9D78 

5680 

21 CF 

AC06 

3000 

39 

9152 

6F8S 

S$UTIL 

ANALZ 

iA12 

7F06 

17E2 

C4CF 

AA04 

4400 

39 

9368 

6FS8 

SfUTIL 

XOI 

620D 

597A 

1998 

25CF 

A906 

3000 

39 

92B0 

6F88 

SSUTIL 

FILEMGR 

0502 

90A4 

C04C 

249F 

0024 

D320 


920E 

6D96 

SSSHIP 

SC I 990 

0101 

7EC6 

7C78 

21CF 

D005 

1000 


9152 

6D96 

S$UTIL 

LGACCT 

47F4 

E7EC 

CISS 

C49F 

0005 

F300 


A006 

4C9E 

S^UTIL 

LGFORM 

21E2 

FC5C 

FC3C 

209F 

0004 

C700 


9B92 

4C9E 

S$UTIL 

PMRWTK 

2DD8 

CIDO 

COOS 

849F 

7904 

C500 


9A3C 

4C9E 

S^UTIL 

JOBMGR 

48D7 

EOFC 

C1F6 

C49F 

0004 

C720 


99CA 

4C9E 

S$UTIL 

DISKMGR 

0619 

C006 

C02C 

849F 

0024 

F300 


98C8 

4C9E 

SSSHIP 

PMWRIT 

0817 

C006 

C082 

B09F 

0024 

F320 


9856 

4C9E 

S^SHIP 

I PC 

0614 

C232 

C022 

B09F 

0024 

DlOO 


97E4 

4C9E 

B^UTIL 

PMOVYL 

0713 

C006 

COSA 

849F 

0024 

D120 


9772 

4C9E 

S^SHIP 

SAYRES 

680D 

C008 

C09E 

B09F 

0024 

D300 


9570 

4C9E 

SSUTIL 

FILEMGR 

0509 

90A4 

C04C 

209F 

0024 

F320 


94FE 

4C9E 

S$SHIP 

PMTERM 

0408 

C006 

C264 

D89F 

0005 

F120 


9476 

4C9E 

S$UTIL 

NAMMGR 

4306 

COO A 

COAO 

B09F 

0024 

F120 


937C 

4C9E 

S$UTIL 

lOU 

0305 

C006 

C030 

849F 

0024 

F320 


92F4 

4C9E 

S$SHIP 

PMTLDR 

0404 

C006 

CISC 

309F 

0024 

F320 


9282 

4C9E 

S$SHIP 

DIOU 

7502 

C0B2 

C012 

849F 

0024 

F120 


919E 

4C9E 

S$UTIL 

OPERATOR 

6111 

9022 

C14E 

959F 

7909 

9008 


9656 

4C9E 

S^UTIL 

MAILBOX 

0710 

lADA 

0588 

C5CF 

7909 

1008 


9700 

4C9E 

S$UTIL 

PMTBID 

0203 

C006 

C036 

B09F 

0024 

F320 


9210 

4C9E 

S$SHIP 


Figure 8-3. T ask States and JSB List (Sheet 1 of 2) 
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JSB LIST **** 
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OOOB 
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L. T8 
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4954 
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Figure 8-3. Task States and JSB List (Sheet 2 of 2) 
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The following paragraphs briefly describe each entry of the ANALZ listing shown in Figure 8-3. 

8.2.2.1 Task States. For each task in the system, the task state list contains the task ID, the 
task context at the last time the task was scheduled or performed an SVC, the current state of the 
task, the task flags, the TSB address, the JSB address, and the program file name. You may need a 
list of program files to identify these tasks. The task flag indicates task characteristics. Figure 8-4 
defines the flags in the fiag word. 


0 


2 3 


4 5 6 7 


8 9 10 11 


12 13 14 15 


2279433 


0 — System task 

1 — Privileged task 

2 — Current segment set in memory 

3 — Take end action on error 

4 — I/O has been aborted for task 

5 — Task being aborted 

6 — Bypass security 

7 — Queue server task 

8 — Activate task outstanding 

9 — Initial task bid 

1 0 — Software pri vi leged task 


Figure 8-4. Bit Assignment for the Flag Word 


Bit 2 of the task flag contains information for the active segment of the task at the time of the 
crash. When this bit is reset, the segment of the task has been rolled out to the disk. By examining 
this bit for each task, the systems programmer can determine which tasks were in memory and 
may be associated with the crash. 

8.2.2.2 JSB List. The JSB list contains all global data about the job including the job ID, job 
name, and priority. This information allows the systems programmer to associate a job with the 
task that was executing at the time of the crash. 

8.2.3 Analyzing System Crash Dumps 

The most common types of crashes are >6x (>60 through >6F) crashes and >1x (>10 through 
> 1F) crashes. The following paragraphs give suggestions on conditions to look for when analyz- 
ing these crashes. 

The > 6x crash is caused by an invalid internal interrupt within the system or within a system task. 
Therefore, the status register at the time of failure Is >xxx1. The following steps indicate what to 
look for when a > 6x crash occurs. 
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Register 1 of the interrupt level 2 workspace contains the task error code that caused the crash. 
This code is displayed as a part of the crash code. The contents of registers 13, 14, and 15 show 
the location of the crash and the status at the time of the crash. If bit 8 of workspace register 15 is 
set to 1, the crash occurred in map file 1. If it is set to 0, the crash occurred in map file 0 (in system 
code). Register R14 contains the program counter value at the time of the crash. The 16 memory 
locations around the program countervalue are also printed. Therefore, the systems programmer 
can decode the instructions previous to the program counter value (which was incremented by 2). 
The code around this location indicates the cause of the crash. The systems programmer can use 
the task workspace to check Indexed addresses. For example, if a crash code is >65 (a memory 
mapping violation), the systems programmer should decode the instructions using the task work- 
space register information. 

When a task takes end action, the TSB for the task contains the address of a four-word area that is 
printed following the TSB. These words contain the error code and the context of the task at the 
time end action was taken. In the case of end action taken by a system task, the systems program- 
mer should use this information to determine what forced a task to take end action. The systems 
programmer can then decode the location previous to this program counter value. 

The > lx crash is an illegal interrupt at interrupt level x. This indicates that a device interrupted at 
an Interrupt level that is not defined or a device interrupted from an expansion chassis and its 
position was not defined in the chassis. Check the hardware configuration and the system config- 
uration listing. 

8.2.4 Forcing a System Crash 

A problem can occur in the system without resulting in a system crash, but it might prevent useful 
work on the system. For example, a system task could be in an endless loop. In such a case, it is 
desirable to force a system crash to obtain a crash dump for analysis. 

To force a crash, perform the following steps: 

1. Press HALT twice to ensure that the processor is using map fileO. 

2. Press PC DISPLAY, MA ENTER, CLR, and MDE, In that order, to set current memory 
address to 0. 

3. Press RUN to resume execution. The machine instruction code executed at this point is 
>0000, entered from the programmer panel. This is an Illegal instruction and causes the 
system to crash with crash code > 62. 

4. Now, copy the crash dump to the crash file by pressing HALT and RUN. 

When you force the system to crash, the immediate cause of the crash is the illegal instruction 
you forced the computer to attempt to execute. However, you can examine other information 
(such as the executing task, hardware trap vectors, XOP trap vectors) to determine what caused 
the problem. The systems programmer should look for the location where the crash occurred. This 
location can then be used to trace the task that was executing when the problem occurred. 
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9.1 DNOS MESSAGE AND ERROR PROCESSING 

DNOS uses a single format for error messages from the operating system and all utilities. The 
method DNOS uses for message handling has the following features: 

• It provides informative, consistent messages. 

• It allows you to easily find expanded explanations of the errors. 

• It permits you to add your own messages. 

DNOS offers the following three levels of error reporting: 

• Internal error codes 

• Short, descriptive, English messages with message categories and identifiers used to 
find further explanation 

• Expanded online explanations 

This section describes the addition of messages and expanded explanations. 

Internal error codes appear if the supplied directories of message files are deleted from the sys- 
tem disk. If the directory .S$MSG is on the system disk, short messages are supplied. If the direc- 
tory .S$EXPMSG Is also on the system disk and key indexed file (KIF) support is available, 
expanded explanations for errors are also available. 

9.1.1 Internal Error Codes 

When only the first level of error reporting is available, DNOS generates error messages formatted 
as follows: 

CCCCCCCC — INTERNAL CODE >MMMM VVVVVVVV 
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Message category CCCCCCCC is a one- to eight-character string. The categories used by DNOS 
are as foiiows: 


Category 

Meaning 

ASSEMBLR 

Macroassembler messages 

DEBUGGER 

Task Debugger messages 

DNOSHLL 

DNOS high-level language messages 

EDITOR 

Text Editor messages 

LINKER 

Link Editor messages 

MAIL 

Used by mailbox facility 

SCI 

System Command Interpreter (SCI) messages 

STATUS 

Task status messages 

SVC 

Supervisor call (SVC) messages 

UTILITY 

Utility messages 


Dispiaying the message category CCCCCCCC is optional. Refer to Section 3 for a description of 
the S$CMSG interface routine. 

Error code MMMM is a four-digit, hexadecimal, ASCII-character Internal error code. 

Variable text string VVVVVVVV is an optional, variable-length text string with logically separate 
pieces separated by semicolons. 

9.1.2 Short English Messages 

When the second level of error reporting is available, error messages have the following format: 

SSS CCCCCCCC— NNNN message message message message message message mes- 
sage message message message (as many as five lines) 

Displaying the error source code SSS and message category CCCCCCCC is optional. Error source 
code SSS contains one, two, or three characters. The following is a list of error source code 
characters: 


Code Meaning 

H Hardware 

I Informative 

S System 

U User 

W Warning 

Message category CCCCCCCC Is one of the abbreviations defined for Internal error codes. 

Additional abbreviations are used for support of various programming language and productivity 
tools. The abbreviations used by each language are described in the appropriate manual for the 
language. 

Message number NNNN can be used to locate further explanation of the message in the section 
for category CCCCCCCC within the DNOS Messages and Codes Reference Manual. 


9-2 


2270510-9701 



Adding Error Messages 


9.1.3 Expanded Explanations Online 

For those systems that support expanded message files, the following information is reported to 
the user on request: 

Explanation: Text that explains the probable cause of the error and what the system has 
done 

User Action: Text that explains what the user should do to recover from the condition 

When an error message is displayed, enter a question mark (?) and press the Return key to display 
the expanded error message. 

9.1.4 Show Expanded Message (SEM) Utility 

The SEM utility displays an expanded explanation of a specified error message. You can display 
the expanded explanation of an error message Immediately after the message appears by enter- 
ing a question mark (?), and pressing the Return key. At any other time, you must enter an SEM 
command to display the expanded explanation. The information is written to the terminal local file 
(TLF) and displayed. Enter the command as follows: 

SHOW EXPANDED MESSAGE 

MESSAGE CATEGORY: alphanumeric 

MESSAGE ID: [■CaLphanumeric/integer>] 

INTERNAL ERROR CODE: UNKNOWN/ i ntege r 

The message category is the abbreviation for the category of the desired expanded message file. 
A message can be retrieved according to the message Identifier sent to the screen or by the inter- 
nal error code. A message identifier is the message number sent to the terminal that immediately 
follows the hyphen in the error message. An internal error code is the hexadecimal value used 
internally by DNOS. A common use of the INTERNAL ERROR CODE prompt is to display the mes- 
sage for an error returned to a supervisor call (SVC) block. 

For example, the user might specify the following to display the explanation of the SVC error 
shown for the Assign LUNO Error, numbered 0315: 

SHOW EXPANDED MESSAGE 

MESSAGE CATEGORY: SVC 
MESSAGE ID: 0315 
INTERNAL ERROR CODE: UNKNOWN 

9.1.5 Displaying Messages 

The message is a combination of file-resident text and variable text. The file-resident text can con- 
tain as many as 240 characters. Any character other than the question mark can appear in the text. 
The question mark is used as a position marker. It is replaced by variable text when the message 
is processed. Each question mark is followed by a decimal digit between one and nine to show 
which variable text element replaces the question mark. A question mark (?) followed by the char- 
acter C Implies that the current line of message text is filled with blanks; that is, C is an effective 
carriage return/line feed sequence. 

Variable text is that part of the displayed message that can vary in each display of the message. It 
Is determined at run time. It can be a pathnname, logical unit number (LUNO), opcode, or other 
execution-dependent information. 
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When the message is being formatted for dispiay, the disk-resident portion of the message is 
piaced in the message output buffer. Each question mark is repiaced by variabie text suppiied by 
the task that detected the error. The maximum iength of variabie text is 235 characters. This 
inciudes aii variabie text eiements and deiimiters that may be in the buffer. 

One question mark and digit is used for each eiement of variabie text. When an eiement of variabie 
text is nuii, the question mark remains in the message but the associated digit is removed. An 
eiement can contain as many as 235 characters. 

The variabie text deiimiter is the semicoion. More than one variabie text eiement can be used in 
the variabie text message. Two consecutive semicoions can be used to represent a nuii variabie 
text eiement. 

If the files containing the file-resident portion of the message text are not on the system disk, the 
internal error code (previously described) is displayed. 

9.1.6 Message Examples 

The following examples show typical internal error codes and error messages for two error condi- 
tions. The internal codes, message file texts, and message numbers shown in these examples are 
not necessarily those currently in the system. They are shown to illustrate the formatting of DNOS 
error messages. 

9.1.6.1 Assign LUNO Error. When the file specified in an Assign LUNO operation does not 
exist, the internal error code displayed on a system without a message text file might be as 
follows; 

SVC — INTERNAL ERROR CODE >0027 .PRINT. OUT 

The message category is SVC, the internal error code is >0027, and the variable text is the path- 
name of the nonexistent file .PRINT.OUT. When a message text file is present, an error message is 
displayed. The following is a sample error message for the same error: 

U SVC - FILE .PRINT.OUT DOES NOT EXIST 

The U identifies this as a user error, the message category is the same as that used in the internal 
error code, and the message is a composite of the message text and the variable text. The mes- 
sage text is as follows: 

FILE ?1 DOES NOT EXIST 

The variable text is as follows: 

10. PRINT. OUT 

The character count is a binary value. The characters replaced the ?1 of the message text. 

A message ID in the error can be used to find additional information in the DNOS Messages and 
Codes Reference Manual. It is also the number thau identifies a supplementary message in the 
expanded message file. The following message example contains a message ID: 

U SVC — 0315 FILE .PRINT.OUT DOES NOT EXIST 
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9.1.6.2 COBOL Compiler Termination. The following is a sample display of the internal code 
displayed on a system without a message text file when the COBOL compiler has satisfactorily 
completed: 

COBOL - INTERNAL CODE >9010 .SOURCE;0 

The message category is COBOL. The internal error code Is >9010. The variable text consists of 
the pathname of the source file, .SOURCE, and the number of errors the compiler detected, 0. 

When a message text file is present, an error message is displayed. The error message for COBOL 
completion could be: 

I COBOL — .SOURCE COMPILED WITH 0 ERRORS 

The I identifies this as an Informative message. The message category is the same as that dis- 
played in the internal message code, and the message is a composite of the message text and the 
variable text. The message text is as follows: 

?1 COMPILED WITH ?2 ERRORS 

The variable text is as follows: 

9.SOURCE;0 

The character count is a binary value. The characters of the first element (up to the semicolon) 
replaced the ?1 of the message text. The 0 replaced the ?2. 


9.2 MESSAGE FILES 

Two types of message files can be maintained on the system disk: 

• Message files in the .S$MSG directory provide the fixed text portion of the error, infor- 
mation, and completion messages used by SCI, SVCs, the languages, and utilities. 

• Expanded message files in the .S$EXPMSG directory contain the expanded 
explanations that are displayed when requested. 

Directory .S$MSG contains a message file for each of the language processors, the major utilities, 
and the SVC processors. The Build Message File (BMF) utility allows users to create message 
flies for use in .S$MSG. 

Directory .S$EXPMSG contains an expanded message file corresponding to each message file. 
These files contain expanded explanations of the errors documented in the message files. The 
BEMF utility allows users to create expanded message files for use in the directory .S$EXPMSG. 
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The messages files required by various application processors and utilities should use file names 
unique to those processors. The file name can be any name except those reserved for the system 
communications product and language processors. The following names are reserved: 


ASSEMBLR 

EDITOR 

NIO 

SMRG 

BASIC 

FORTRAN 

PASCAL 

STATUS 

COBOL 

FORT78CP 

PTP 

SVC 

COMM 

FORT78RT 

QUERY 

TAP 

DATADICT 

ICS3270 

RPG 

TIFORM 

DBMS 

LAN 

S$ROUTIN 

TIP 

DEBUGGER 

LINKER 

SCI 

TIPE 

DNCS 

DNOSHLL 

MAIL 

SLA 

UTILITY 


To enable flexible naming for files, the source code contains a file indicator instead of the file 
name. The system uses the file indicator (hexadecimal value between > 00 and > 7F). This file indi- 
cator is associated with a file name by a synonym $$FNxx in the SCI command procedure that 
calls the application processor. 

Application programs written by users can use files with file indicators greater than >7F. Any 
conflict between file indicators In user programs is resolved by avoiding any common files or 
command procedures. 

9.2.1 Format of the Message Text Files 

The message file is written by a utility called by the Build Message File (BMF) command. The Input 
to this utility is a blank-suppressed sequential file. A file written by the Text Editor with default 
parameters is the intended input. A record length other than the default 80-character record length 
can be used. The following paragraphs describe the file contents. 

The first record of a message text file Is a heading line. It must contain the following information: 

• The lowest-value internal error code in the file in columns 1 through 4 (4 digits) 

• The highest-value internal error code in the file in columns 6 through 9 (4 digits) 

• The local language character for U (user error) in column 1 1 

• The local language character for S (system error) in column 12 

• The local language character for H (hardware error) in column 13 

• The local language character for W (warning) In column 14 

• The local language character for I (Informative) in column 15 (the second record should 
be a blank line) 
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Individual messages begin in record 3. Each message in the fiie has a header containing the 
foiiowing fieids: 

• The error source indicator or combinations (such as USH) 

• Oneor more bianks 

• A ieft parenthesis 

• One or more four-digit hexadecimai internai error codes (separated by commas) 

• A right parenthesis 

This header can extend to severai 80-character iines when the appiicabie internai error codes can- 
not aii be written on one iine. Terminate each line with the comma that separates the iast internai 
error code on the iine from the first code on the next iine. 

The text of the message begins in coiumn 1 of the next iine and can be up to three iines iong. This 
provides a maximum of 240 characters for the fixed-text portion of a message. The message iO, 
when it is to be dispiayed, precedes the message text on the first iine and is inciuded in the maxi- 
mum number of characters. The message text is foiiowed by a biank iine. A text message can con- 
tain any printabie characters, with the foiiowing restrictions: 

• A question mark (and digit) anywhere in the message is repiaced with variabie text 
suppiied by the task that reported the error. 

• The question mark and digit pair can be set off by bianks, have a biank on one side, or 
have nonbiank characters on both sides. 

• A message can inciude as many as nine question marks, but none are required. 

A message can be associated with many internai error codes or with oniy one. The internai error 
code, perhaps by means of an EQU directive, appears in the source code of the task that issues an 
error message rather than the message itseif. This aiiows you to add, modify, or deiete messages 
without changing the source code. 

The internal error codes used within one message text file are independent of those used in 
another file. The user can choose any range of values. The values should be continuous to mini- 
mize file space required since the .S$MSG file built from the message text file includes a con- 
tinuous table of internal message numbers and their corresponding record numbers in the 
.S$MSG file. 

The standard message text files found in the .MESSAGES.TEXT directory have messages in 
uppercase English. 
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The following is an example of a message text file: 

9050 9070 USHWI 
SU (9050) 

0059 ERROR ENCOUNTERED IN ASCII CONVERSION 
U (9052,9070) 

0061 ATTEMPT TO MODIFY BYTE AT AN ODD ADDRESS 
I (9053) 

0062 MODIFICATION PREVIOUSLY APPLIED 

The following example shows a message text using this file and internal error code 9051. The 
message category UTILITY is determined by selecting the file. The error source code S is supplied 
by the task that issues the message. The complete message displayed is as follows: 

S UTILITY— 0060 INTERNAL SUBROUTINE ERROR ENCOUNTERED 

9.2.2 Format of the Expanded Error Message Text Files 

The expanded message file is written by a utility called by the Build Expanded Message File 
(BEMF) command described in paragraph 9.3.2. The input to this utility is a blank-suppressed 
sequential file of 80-character records (normal Text Editor output), as described in the following 
paragraphs. 

Each message file can have a companion expanded message file in the expanded message file 
directory. This file should have the same name as Its counterpart in the message file directory. 
These files contain the explanation and user action portions of the messages that appear in the 
DNOS Messages and Codes Reference Manual. The files for system messages contain text in 
uppercase and lowercase. 

Record 0 of an expanded message text file contains the characters for the headings for the mes- 
sages (Explanation and User Action). These are in the same language as the messages in the file. 
Each heading must be enclosed in quotation marks to allow blanks in the phrases when 
appropriate. 

Subsequent records contain an explanation message and a user action message. For each pair of 
messages, the records contain the following: 

1. The characters %% are followed by a message identifier of up to 14 characters. The 
identifier must be the same as the external message number specified for this message 
in the .TEXT file. The pairs % % 1 and % %2 are reserved for the system. 

2. Starting on a new line, a paragraph explaining the message. The paragraph can contain 
as many as 20 lines. 

3. A blank line. 
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4. A paragraph describing user action when the message is seen. The paragraph can 
contain as many as 20 iines. 

5. Abiankiine. 

Expanded expianations shouid be inciuded for aii of the entries in the message text fiie that con- 
tain message IDs. The standard expanded message text files are found In the 
.MESSAGES.EXPTEXT directory. The following example shows an expanded message text file 
that corresponds to the example .TEXT file in the previous section. 

%%0059 

The attempt to convert to ASCII resulted in an error. 

Examine the program and determine why the input for the conversion was in error. 

%%0061 

The address specified for the change was an odd address. This routine does not process 
addresses with an odd value. 

Determine the source of the address, correct the error, and try the operation again. 

%%0062 

The requested modification has already been made. 

This is an informative message only. 


9.3 MESSAGE FILE UTILITIES 

Three utilities are provided to build and use the message files. One of these utilities builds the 
message files from the message text files. Another creates expanded message files from the 
expanded message text files. A third utility retrieves the expanded explanation for the message ID 
given by the user. 

Each of these utilities is called by an SCI command. Figure 9-1 shows the functions of the utilities 
that process the message text files and the expanded message text files. 
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User Directory 
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Figure 9-1. Functions of Message File Utilities 


9.3.1 Message File Utility 

To create a message file in the .S$MSG directory, first write a message text file in any user direc- 
tory. Then, use a Build Message File (BMF) command to write the file in the .S$MSG directory. The 
command is as follows: 


BUILD MESSAGE FILE 

INPUT FILENAME: 
OUTPUT FILENAME: 
OUTPUT FILE TYPE(REL/SEQ) : 

ERROR ACCESS NAME: 
MAXIMUM MESSAGE TEXT LENGTH: 


f i Lenameffl 
f i L enamea 
REL/SEQ 
f i Lenamea 
i nt eger 


(RED 

(DUMY) 

(80) 


The input file name is the file pathname of the message text file that contains error messages for 
user programs. The output file name is the file name that must be placed in the .S$MSG directory 
for use by DNOS. The error access name is the pathname of a listing file used to document any 
errors in the message text file. If errors occur, correct them and reenter the command. The output 
file can be either a sequential or a relative record file. A relative record file (the default file) is 
accessed in less time. However, you can specify a sequential file when file size is important. The 
sequential file is more compact. The maximum message text length is the logical record length of 
the message text file specified as the input file. It is normally 80 characters. No translation of 
lowercase to uppercase is available. It is expected that the message text file contains uppercase 
letters. The .S$MSG file is also in uppercase letters. ♦ 
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9.3.2 Expanded Message File Utility 

SCI can display any expanded explanation of the errors documented in the user message files. 
The expanded message text file can be developed in any user directory. You can then prepare this 
fiie for directory .S$EXPMSG by using the Bulid Expanded Message Fiie (BEMF) command. Flies 
in directory .S$EXPMSG are KIFs. 


BUILD EXPANDED MESSAGE FILE 

INPUT FILENAME: 
OUTPUT FILENAME: 
ERROR ACCESS NAME: 
CONVERT LOWER TO UPPER CASE?: 
MAXIMUM MESSAGE ID LENGTH: 


f 1 L enamea 
f1 lenamea 
fi Lenamea 
YES/NO 
integer 


(DUMY) 

(NO) 

(4) 


The input file name is the fiie pathname of the expanded text fiie. The output fiie name is the name 
of the file that must be placed Into the .S$EXPMSG directory for use by DNOS. The error access 
file is the file pathname of a file that is used to document any errors In the expanded message file. 
When errors occur, delete the output file. Correct the expanded message file and reenter the 
BEMF command. 

Respond YES to the CONVERT TO UPPERCASE prompt when the system includes terminals that 
do not support lowercase characters and the Input file contains lowercase letters. Otherwise, you 
can respond NO to the prompt. 

The maximum message ID length is the length of the message number that Is used to select the 
expanded explanation. The default value is 4. You can specify any value from 1 through 14. 


9.4 ERROR MESSAGE INTERFACE 

An application program uses routines S$TERM and S$CMSG (described In Section 3) to Interface 
with the message files. Section 3 also describes the system synonyms related to these routines 
($$CC and others). 

Command procedures that use the application message file need to set a synonym $$FNxy to the 
message file name in use. The value chosen for xy must be greater than > 7F and must not conflict 
with any other application message file in use. The value assigned to the synonym must be the 
last component of the file name in the .S$MSG directory. For example, an accounting package 
might have a file .S$MSG.ACCOUNT for which the synonym $$FN80 is set to ACCOUNT in each 
command procedure used by the accounting application. 
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10.1 INTRODUCTION 

DNOS is an international operating system designed to meet the commercial requirements of the 
United States as well as most Western European countries and Japan. 

The international capabilities include the following: 

• Data input and output via international peripheral devices designed to meet the 
language requirements of the following countries: 

Denmark/Norway 
France/Belgium 
French word processing 
Germany/Austria 
Japan 

United States 
United Kingdom 
Sweden/Finland 
Spain 

Switzerland 

• The ability to store and manipulate international data on any of the DNOS file types 

• Collating sequences dependent on country code for key indexed files (KIFs) 

• T ranslatable error messages 

• Translatable of SCI procedures 

• Use of special language characters In pathnames and synonyms 
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10.2 COUNTRY CODE 

DNOS interprets international data in accordance with the country code selected by the user dur- 
ing system generation. This code reflects the nationality of the data terminals attached to the sys- 
tem and defines the way data is processed for the complete user system. It also determines the 
way the device service routines (DSRs) interpret input and output data and the way in which (KIF) 
management orders user keys. 

The country codes that can be assigned during system generation are as follows: 

Response to 
Country Code 
Prompt 

AU 
B 
D 
FI 

FRA 
FWP 
G 
J 
N 

SP 
SWE 
SWI 
UK 
US 


Country 

Austria 

Belgium 

Denmark 

Finland 

France 

French Word Processing 

Germany 

Japan 

Norway 

Spain 

Sweden 

Switzerland 

United Kingdom 

United States 


NOTE 

For countries not listed, users should enter the default value (US) 
for the country code prompt during system generation. 


When using SCI, you can use the Show Country Code (SCC) command to show which country 
code is currently set. Table 10-1 shows the ASCII codes for special language characters. User pro- 
grams can determine the country code assigned to their system by executing a Retrieve System 
Information (> 3F) supervisor call (SVC). 
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Table 10-1. ASCII Codes for Special Language Characters 


ASCII CODE 


COUNTRY 

23 

40 

5B 

5C 

5D 

5E 

60 

7B 

7C 

7D 

i 

1 

US ASCII STANDARD 


@ 

[ 

\ 

] 

A 

- 

i 


! 

- 

UNITED KINGDOM 

£ 

@ 

[ 

\ 

J 

A 


i 


1 


GERMANY/AUSTRIA 


@ 

A 

6 

u 

A 

- 

a 

6 

ij 

P 

SWEDEN/FINLAND * 

# 

E 

A 

6 

A 

U 

e 

a 

6 

a 

ii 

NORWAY/DENMARK 

# 

@ 

/E 

0 

A 

A 


ae 

0 

1 

a 

' 

SPANISH -SPEAKING 

# 

@ 

i 

N 

i 

A 


o 

n 

? 

- 

SWITZERLAND 

FRANCE ** 

£ 

a 

e 


e 

A 


a 

6 

u 


FRENCH WP 

ITALY ** 

HOLLAND ** 

£ 

a 

o 


§ 

1 

A 


e 

u 

e 



* USES ASCII CODE >24 , REPLACING THE S CHARACTER IN US ASCII . 

**USES THE US ASCII STANDARD. 

2284937(t/2) 


10.3 INFORMATION INTERCHANGE CODES 

DNOS and its supported peripheral devices use the internatlonaliy accepted information inter- 
change codes for the various countries supported. In most cases, this is a seven-bit ASCII-type 
code with a few special characters required for the local language. 

Japan uses an eight-bit code to represent both the Latin alphabet (A through Z) and the Japanese 
Katakana character set in one combined information interchange code (JISCII). Devices using this 
code must be put in 8-bit mode by using the Modify Device State (MDS) command. For details 
about the MDS command, refer to the DNOS System Command Interpreter (SCI) Reference 
Manual. Table 10-2 shows the JISCII codes for Japanese characters. 

The Japanese Model 91 1 VDT, which supports this extended character set, does not have the high/ 
low intensity features available on the other versions of the Model 91 1 . 
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Table 10-2. JISCII Codes for Japanese Characters 


JISCII 

CODE 

5C 

A1 

A2 

A3 

A4 

A5 

A6 

A7 

Ae 

A9 

AA 

AB 

AC 

JAPANESE 

CHARACTER 


o 

1” 

-I 


- 


-P" 

-■r 

•y 





JISCII 

CODE 

JAPANESE 

CHARACTER 


Jl SCI I 

CODE 

JAPANESE 

CHARACTER 


JISCI I 
CODE 

JAPANESE 

CHARACTER 


JISCII 

CODE 

JAPANESE 

CHARACTER 


AO 

AE 

AF 

BO 

B 1 

B2 

B3 

B4 

B5 

B6 

B7 

Be 

B9 


3 

•y 

— 

~F 

Y 

o 

ZXL 


n 

=f= 




BA 

BB 

BC 

BO 

BE 

BF 

CO 

C 1 

C2 

C3 

C4 

C5 

C6 

Z3 



.-rr 

tzr 







-y~ 

— 


C7 

C8 

C9 

CA 

CB 

cc 

CD 

CE 

CF 

DO 

D 1 

D2 

D3 

= 5 ^ 




t=Z 




•ry 

— 


>1? 



04 

D5 

D6 

07 

08 

D9 

DA 

OB 

DC 

DO 

DE 

DF 


T* 


a 


• } 

IL' 

L 

a 

■-7 



0 



2284937 ( 2 / 2 ) 


Local character extensions to ASCII required for international ASCII often replace special charac- 
ters. The brackets ( [ ] ) used for the SCI prompt may not be available; local characters may have 
replaced them. For example, in German, the letters A U replace the brackets in the default SCI 
prompt. You can supply an appropriate substitute by entering the .OPTION SCI primitive. The for- 
mat of the primitive is as follows: 

.OPTION PROMPT = “Any message” 
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10.4 KIF COLLATING SEQUENCES 

The KIF manager sorts user keys alphabetically (rather than according to the hexadecimal value 
of the letter) as it inserts records in a KIF. In German, Austrian, Swedish, Danish, Norwegian, and 
Finnish, the aiphabetic order differs from English and a special collating sequence appiies. 

The country code specified for the system determines the coliating sequence for KiFs. For ex- 
ampie, the key ietters V, U, U, and D are sorted by KiF as D, U, II, and Vina German system. 

Key Order Hexadecimal 

on Disk (German) Value 

D 44 

U 55 

U 5D 

V 56 

Once a KIF is written on a German system, the collating sequence In which the data is arranged is 
valid only for a German system. For example, if the file Is physically transferred to a Swedish sys- 
tem and a Show File (SF) command is executed, the data appears reasonably legible, although the 
U appears as an A on the Swedish VDT. However, the alphabetic sorting order of the keys is incor- 
rect for the Swedish system. The Swedish A should not appear between the U and the V in the col- 
lated access list. If you attempt to add data to the file, the key collating sequence is disrupted and 
the file becomes unusable. 

If you use binary data as keys, you may have several values that map to the same positions in 
sorted order. At most, the last four byte values of the ASCII codes will sort to the same value; that 
is, > FC, > FD, > FE, and > FF will all sort at the end as > FF. 

To successfully transfer a KIF between different international systems, convert the file to a 
sequential file by using the Copy KIF to Sequential File (CKS) command on the system on which 
the file was written. Then, create the KIF on the destination system. Use the Copy Sequential File 
to KIF (CSK) command to copy the records using the collating sequence of the destination sys- 
tem. Since the new KIF is compatible with the destination system, you can insert records correctly 
using the CSK command. 
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Table 10-3 shows the collating sequences for all supported languages. 


Table 10-3. Collating Sequences for All Supported Languages 


Country 

Collating Sequence 

France/Belgium 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghi jklmnopqr stuvwxyz 

France Word Processing 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
aabcpdeeef ghi j klmnopqr stuuvwxyz 

Germany/Austr ia 

AABCDEFGHIJKLMNOOPQRSTUtiVWXYZ 
aabcdefghi j klmnoopqr sptuiivwxyz 

Japan (Katakana) 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghi j klmnopqr stuvwxyz 


ac TT f 3, =1 *y — ^ 

-r o ic m =f = ^ rr 

J 'I tz: Jts ^ = ZIL ^ T- ZL 

Nor way /Denmark 

ABCDEFGHIJKLMNOPQRSTUVWXYZ imk 
abcdefghi j klmnopqr stuvwxyz aeoa 

Sweden/Finland 

ABCDEEFGHIJKLMNOPQRSTUVWXYUZAAO 
abcde^fghij klmnopqr stuvwxyuzaao 

Spanish -speaking 
countries 

ABCDEFGHI JKLMNNOPQRSTUVWXYZ 
abcpdefghij klmnnopqr stuvwxyz 

Switzerland 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
aaabcpdeeefghi j klmnoopqr stuiivwxyz 

United Kingdom 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 
abcdefghi j klmnopqr stuvwxyz 

2283037 
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10.5 INTERNATIONALIZING MESSAGES 

Section 9 describes the DNOS message facility In detail. The messages reside in a set of files, 
which facilitates translating them into the local language. 

The .MESSAGES.TEXT directory contains the files of factory-built text messages in a form that 
can be text edited. Separate files are available for each of the language processors, System 
Command Interpreter (SCI), the major utilities, SVC error messages, and user-developed 
messages. 

The header record (first record) of each file contains the local language letters that correspond to 
the error source code letters U, S, H, W, and I. (See the paragraph entitled Short English Messages 
in Section 9 for the meanings of the error source code letters.) Edit that record to place the proper 
letters in columns 1 1 through 15 as described in the section on message files. 

For each error message, the .MESSAGES.TEXT directory contains edit files with source code, the 
internal error codes that select the message, and the message text. Edit the error source code 
field, substituting the letters defined in the header record for those in the file. Then edit the mes- 
sage text, replacing the English words with a useful translation to the local language. You must 
also edit the corresponding expanded messages in the .MESSAGES.EXPTEXT directory. 

Edit the messages with care. To obtain the support you might require from time to time there must 
be a one-to-one correspondence between the English messages supplied by the factory and the 
messages in your language. Support personnel can locate the message associated with each 
internal error code and can recognize the message number but may not understand the transla- 
tion. By retaining the internal error code relationship to the message and the message number 
relationship to explanatory information, you simplify support procedures. 

To generate the .S$MSG and .S$EXPMSG directories from the files that you edited, execute the 
batch stream named . BATCH. BUILD.MESSAGE1 that is shipped with DNOS. 
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11.1 INTRODUCTION 

This section describes some of the differences between DX10 and DNOS that affect migrating 
from DX10 to DNOS. it aiso offers advice to help you overcome the differences. The categories of 
differences are as follows: 

• General environment 

• Device and file I/O operations 

• System Command Interpreter (SCI) user interface 

• SCI primitives and interface routines 

• Supervisor call (SVC) support 

• User-written system software 

• System console 


11.2 GENERAL ENVIRONMENT 

Most DX10 operating system applications programs can execute properly under DNOS. However, 
the environment in which they run is slightly different. Consequently, the programs might require 
several subtle changes. 

One of the features of DNOS is the job structure which allows the user to isolate a set of tasks 
with its own resources and run-time environment. Each task in DNOS exists within a job. A job can 
have job-local logical unit numbers (LUNOs), semaphores, and logical names. Access to many 
task characteristics is restricted to tasks within a single job. Among other things, the job struc- 
ture allows some characteristics that are associated with a terminal in DX10 to be independent of 
a terminal in DNOS. 
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Some of the particular differences between DX10 and DNOS with respect to the overall environ- 
ment include the following: 

• DX10 has no job architecture; the entire system essentially consists of one job. In 
DNOS, the job architecture allows users to isolate their tasks and resources from each 
other. This implies that a number of SCI commands and SVC operations produce differ- 
ent results under the two systems. In particular, status commands such as Show Task 
Status (STS) and Show I/O Status (SIS) provide status for a particular job name or ID in 
DNOS rather than displaying status for all tasks as in DX10. Similarly, the Kill Task (KT) 
command affects only tasks in the user’s job in DNOS, while It may be used for any task 
in DX10. Also, DNOS provides a number of job status commands that are not in DX10. 
An operator interface is also provided so that a system operator can control any job in 
the system. The operator job is recognized by the operating system as a privileged job. 

• Files written in a DX10 environment may be used directly in a DNOS environment, with 
the exception of hash-placement key indexed files. Only sequential-placement KIFs are 
supported in DNOS and in current releases of DX10. 

• During a DNOS initial program load (IPL), all disk volumes that are online are installed. 
In DX10, disk volumes must be explicitly installed. 

• DX10 requires a minimum main CPU memory of 256K bytes (where K equals 1024); DNOS 
requires at least 512K bytes. In general, running DNOS with the same user environment 
as DX10 requires more main CPU memory. 

• DX10 restricts the use of a given user ID and passcode to one terminal at a time. DNOS 
allows the same user ID and passcode to be active in any number of jobs at any number 
of terminals at any one time. This feature can have a confusing effect on the permanent 
synonyms and logical names for the user ID, since each log-on receives the currently 
defined set of synonyms and logical names from a disk file and each log-off saves the 
current set to the file. 

• The system log device in DX10 can also be used as an SCI terminal. This is not allowed 
in DNOS, since a terminal being used for SCI is owned and opened by the job using the 
terminal. When SCI is in use at a terminal, the system job cannot assign a LUNO to the 
terminal and use it for logging. The log device becomes disabled if the terminal is in use 
when a log message is to be sent. To establish the terminal as the log device, use the 
Initialize System Log (ISL) command. 

• In addition to the temporary files which can be created with the Create File I/O opera- 
tion, the DNOS environment supports job temporary files. These files are established 
using the Assign Logical Name (ALN) SCI command or the Assign Logical Name 
suboperation of the Name Manager SVC. A job temporary file is available only to tasks 
within a given job and the file exists only for the duration of the job. 
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The hard-break key sequence for DNOS and for DX10 is Attention/(Control)x. The 
sequence can be redefined by a user who modifies a DNOS tabie of command defini- 
tions. The sequence of tasks kilied in response to severai break key sequences may dif- 
fer in DX10 and DNOS. in DX10, oniy foreground tasks can be kiiied; SCi, however, 
cannot be kiiied. in DNOS, one task is kiiied each time the break key sequence is used, if 
oniy SCi is active, it is kiiied. The job at the terminai terminates and the terminai is again 
avaliabie for use. if tasks other than SCi are active, the order in which tasks are kiiied is 
foreground tasks, then background tasks, then SCi. 

Nonrepiicatabie tasks instaiied in the program fiie .S$PROGA for DX10 have the same 
run-time iD as instaiied iD when they are bid. in DNOS the iDs are not the same when bid 
from the anaiogous program fiie .S$UTIL. User-written command procedures that do not 
check the run-time iD synonym $$RI (which is set by the Execute Task (XT) command) 
must be changed to execute properiy in both DX10 and DNOS environments. 

Many internai system structures of DNOS are different from their counterparts in DX10. 
User programs that access structures such as the task status biock (TSB) must be dif- 
ferent for the two operating system environments. 

For those with DX10 Reiease 3.3 or eariier, a Copy Directory (CD) command for a DNOS 
directory changes channeis to aiiases and does not copy software priviieged tasks in a 
DNOS program fiie correctiy. 

Names of system fiies for various uses differ in DX10 and DNOS, as shown in Tabie 11-1. 

in DNOS, when the destination for instaiiing a task is specified as LUNO 00, fiie 
.S$SHARED is impiied; in DX10, .S$PROGA is impiied. Specifying attached procedures 
not from a task’s program fiie impiies they are in the .SSSHARED program fiie in DNOS. 

The format of the S$CRASH fiie differs for the two systems. Therefore, if a disk with 
S$CRASH written by DNOS is ioaded under DX10, it must be ioaded twice. The first ioad 
faiis but prepares the crash fiie for the second ioad. 

DX10 provides conversion utiiities to transport data in TX990 format to the DX10 disk 
formats. DNOS does not provide this faciiity. 

DX5 support is not avaiiabie with DNOS, but is avaiiabie with DX10. 

DNOS does not support the Ti Li NK software package, but DX10 does. 

DNOS does not support the 913 terminai and FD800 diskette, but DX10 does. 
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Table 11-1. DX10/DNOS System File Names 


System File Name 

DX10 

DNOS 

Log file 1 

.S$SLG1 

.S$LOG1 

Log file 2 

.S$SLG2 

.S$LOG2 

Accounting log file 1 

None 

.S$ACT1 

Accounting log file 2 

None 

.S$ACT2 

Program file 

.S$IMAGES 

System name 

(system kernel) 



Utilities program file 

.S$PROGA 

.S$UTIL 

User’s shared program file 

.S$PROGA 

.S$SHARED 

System generation library 

.S$SYSGEN 

.S$SGU$ 

SCI command library (default) 

.S$PROC 

.S$CMDS 

Swap File 

.S$ROLLA 

.S$ROLLD.S$ROLLA 


11.3 DEVICE AND FILE I/O OPERATIONS 

Because the job orientation in DNOS repiaces the station orientation of DX10 to some extent, the 
scope of LUNOs for i/O is different. DNOS I/O processing in general is more uniform than that of 
DX10. This introduces some differences in the user interface to the system. File management dif- 
fers in the variety of options available. DNOS provides a number of options not available in DX10. 

Particular differences between DX10 and DNOS include the following: 

• In DX10 an Open operation is not required for record-oriented devices. In DNOS an Open 
operation is required before I/O to any I/O resource is allowed. 

• In DX10, the data buffer address field (bytes 6 and 7) of an Assign LUNO I/O SVC block 
has no data returned to It by the I/O processing. In DNOS, resource type information is 
returned from the physical device table (PDT). This is different from the data returned by 
an Open operation. This difference should affect only those programs that reuse an SVC 
block for another call without clearing relevant fields first. 

• In DX10 global LUNO 00 is assigned to ST01; In DNOS it is assigned to DUMY. This dif- 
ference should affect only those programs that are not associated with a specific ter- 
minal when bid but that perform I/O to LUNO 00. 

• Station-local LUNOs, as specified by particular flag settings in DX10 code, are 
interpreted as job-local LUNOs in DNOS. DNOS does not support station-local LUNOs. 

• A task bid by SCI in the DX10 environment can assume that station-local LUNO 00 is 
assigned to the user’s terminal. When a job is created in DNOS, it is given a job-local 
LUNO 00 assigned to DUMY. In DNOS, a task-local LUNO 00 is assigned to the user’s 
terminal. This difference should be noticed only by a program which explicitly tries to 
assign task-local LUNO 00. 
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Communications software in DX10 uses the error byte of the I/O SVC block for informa- 
tive codes as well as error codes. DNOS uses the error byte only for errors and sets the 
error flag in the system flags byte whenever the error byte is nonzero. DX10 communica- 
tions software does not expect the error flag to be set for informative codes. 

A task that enters its end-action routine in DX10 has LUNOs released before entering 
the end-action code. DNOS tasks can use the LUNOs In their end action code without 
having to reassign them because DNOS does not release LUNOs before taking end 
action. DNOS time-out during end action can be set using the Modify Scheduler/Swap 
Parameter (MSP) command. The default is 100 system time units. 

DNOS and current releases of DX10 support sequential-placement KIFs. Hash- 
placement files created under previous versions of DX10 must be converted to 
sequential-placement files on a DX10 system before attempting to use the files with 
DNOS. 

On any KIF I/O operation in which a key is specified, DNOS requires that the key speci- 
fied flag be set in the user flags byte (byte 5) of the SVC block, while DX10 does not. The 
operations for which the flag must be set include the following: 

— Subopcode 41 (Read Greater) 

— Subopcode 44 (Read Equal or Greater) 

The extended call block flag of the user flags byte (byte 5) of the I/O SVC block is used in 
TX990 to mean logical track addressing. DX10 contains a special code to ignore it If set 
for devices that are not terminals. DNOS does not contain this code. 

The DNOS I/O system stores two more words of the I/O SVC block than DX10 does for 
sequential file I/O. These two words are not returned to the task. Therefore, a problem 
arises only if the call block is at the end of the task address space where two more 
words are not available. 

The device LP$1 designates use of LP01 as a print device in DX10. In DNOS, LP$1 func- 
tions as a print device only if it is defined as a logical name for one of the line printers in 
the system. 
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11.4 SCI USER INTERFACE 

DNOS SCI provides essentially the same user interface to the operating system as DX10 SCI. Sev- 
eral differences take advantage of new features in DNOS, and some differences provide a more 
uniform interface. A number of enhancements in speed and space have been developed. The 
specific differences are as foiiows: 

• DNOS provides a synonym and logical name table for each job; DX10 has a synonym 
table for each station. The tables for DNOS are considerably larger than those for DX10. 

• After a DNOS system Is generated, a Modify Spooler Device (MSD) command must be 
executed for each device to be used with the Print File (PF) command. MSD sets up the 
appropriate tables for the spooling of output. All output from PF is through the spooler 
subsystem of DNOS. When the spooler is active, ali devices that have been modified to 
be spooi devices are availabie only to the spooler. Therefore, a command such as List 
Directory (LD) cannot have its output directed to a spooled device. It can be directed to a 
file which is then printed with PF, to a nonspooled device, or to a spooler logical name 
(that is, a logical name that has been assigned to a device available to the spooler). 
Batch streams written for DX10 that specify a line printer for output listings may require 
modification to run on DNOS. 

• The Print File (PF) command in DX10 calls the Show Output Status (SOS) command to 
show the current queue of files to the device specified for output. The DNOS PF com- 
mand does not call SOS; the user must explicitly specify SOS after PF to monitor the 
output. 

• In DX10 the status of each terminal is reinitialized via a Modify Terminal Status (MTS) 
command during each IPL. In DNOS this is not required because the MTS command 
modifies the status on a disk file and not In memory only. This may not be a problem for 
most users. However, it may be a problem to the user who expects the terminal to return 
to the default status during an IPL. 

• DX10 SCI supports two types of task modes, foreground and background. DNOS sup- 
ports the same two types of task modes in Interactive jobs. In addition, DNOS supports 
batch jobs in which tasks run independently of a terminal. Batch jobs, like background 
tasks in interactive jobs, request that SCI process a file of commands (batch stream) as 
its primary input. Some batch streams that can be executed with Execute Batch (XB) in 
DX10 or DNOS cannot be executed with Execute Batch Job (XBJ) in DNOS. This is 
because the values of the synonyms $$ST and ME and the pathname of the terminal 
local file (TLF) are different when SCI is started with the XBJ command. The value of 
$$ST Is 00, and the synonym ME is not assigned when using XBJ. This problem should 
not occur for most batch streams. 

• The primary command procedure library is named .S$CMDS in DNOS; it is .S$PROC in 
DX10. Batch streams that include a .USE that specifies .S$PROC for DX10 must specify 
.S$CMDS for DNOS. 

• In DX10 each of the major subsystems reports error and status conditions in its own 
way; in DNOS the error reporting mechanism is the same for all subsystems. 
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11.5 SCI PRIMITIVES AND INTERFACE ROUTINES 

The structure of the SCI task in DNOS is different from that in DX10. DX10 SCI consists of a task 
with a number of overlays for various support functions such as modifying synonyms, handling 
user IDs, editing, and debugging. In DNOS, SCI is a single task and most of the utility functions 
are performed by independent tasks. Other differences in SCI interfaces and the primitives 
include the following: 

• User-written SCI command procedures and batch streams that directly bid standard SCI 
utilities using .OVLY or .BID instead of using the standard command procedures in 
DX10 do not execute without modification for DNOS. The reasons are as follows: 

— The parameters for .BID have been augmented and defaults have been changed. 
Specifying a bid from LUNO = 00 indicates use of the program file .S$PROGA (the 
system program file) In DX10, but it specifies .S$SHARED (the shared procedure 
program file) in DNOS. The program file in use for .BID can be specified explicitly 
using the PROGRAM FILE= option in DNOS. Use of UTILITY as a keyword speci- 
fies a bid from the utilities program file in DNOS, .S$UTIL. 

— .OVLY is not supported in DNOS. 

— Task IDs for standard system utilities in DX10 are not tne same as those used for 
DNOS. Therefore, bidding a task using the same installed ID for both operating 
systems probably fails. 

— Some utilities require different PARMS lists on the .BID for DNOS and for DX10. 

— Some utilities write out headers in DNOS using the .DATA primitive in the com- 
mand procedure rather than having the text for the header in the utility itself, as in 
DX10. The effect of this difference is that in some cases of errors, the header 
appears as well as the error and a carriage return must be performed to receive the 
error message. 

• The synonyms representing Text Editor active ($$EA) and Debugger active ($$DA) are 
set by different tasks and to different values in DNOS than in DX10. In DX10 these 
synonyms are set by SCI just before reading a command from its primary input device 
(terminal or batch stream). In DNOS these synonyms are set by the Text Editor and 
Debugger tasks. In addition, these synonyms are both set by DX10 SCI to a value of N 
when SCI is started. DNOS SCI does not do this. The synonyms have no values until the 
appropriate utility sets them. Any user-written command procedure that accesses these 
synonyms may require changes. 

• Any user task that is linked with SCI run-time routines for DX10 must be relinked with 
DNOS SCI run-time routines. The DNOS versions of S$ routines must be used for tasks 
that run in the DNOS environment; the DX10 versions do not run in DNOS. The same 
caution applies to linking language programs with the S$ routines. 

• If an error occurs on the open of a file in S$OPEN, the error code returned is > 906A and 
not > 01 XX, where xx is the error byte. 
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Programs can be written in DX10 that iink in S$STOP without linking in S$MAPS and 
S$SETS. This is not possible in DNOS. Two problems might arise: 

— An error can occur when linking the program if the link control file explicitly 
includes the S$ routines rather than making use of a LIBRARY command at the 
beginning. 

— The program can require more memory. This Is not likely, however, since most of 
the DNOS S$ routines are shorter than the DX10 versions. 

In DNOS, the synonym $$CC is set by some standard utilities that do not set the syn- 
onym in DX10. Many utilities in DNOS set $$CC to a different value. This change was 
made to support DNOS error handling facilities. The change should not be noticed 
unless a batch stream includes a test for an explicit value of $$CC instead of testing for 
zero or nonzero values. Batch streams that must check for a particular error code in 
DNOS must access the synonym $$MN instead of $$CC. See the DNOS Messages and 
Codes Reference Manual for the exact message number to match a particular error 
code. 

User IDs in DNOS can be eight characters long but only six characters long in DX10. 
Therefore, the value of the synonym $$UI can be set by SCI to an eight-character value in 
DNOS and a six-character value in DX10. This may be a problem when the synonym 
value is used as part of a pathname and consists of eight characters in DNOS. 

The left bracket, right bracket, and back slash characters are valid characters in items 
of type NAME in DNOS SCI. For example, .OPTION PROMPT = [@ME] results in the 
prompt of [ME] in DNOS rather than the station number enclosed in brackets as in DX10. 
These characters serve as terminators when DX10 SCI scans for the end of an item of 
type NAME. Internationalization requires this change because several other alphabets 
require that equivalent ASCII code be allowed In items of type NAME. Using [@ME'^] 
resolves to the station number in either system. 


11.6 SVC SUPPORT 

The following are the differences between DNOS and DX10 support of SVCs in user tasks: 

• In DX10, a task that Issues an undefined SVC is terminated or goes into its end-action 
routine. DNOS returns an error code in the SVC block. The task continues to execute at 
the instruction following the SVC. 

• DNOS supports the following SVCs that DX10 does not support: 

— SVC > 00: Create I PC Channel (subopcode 9D), Delete I PC Channel (subopcode 9E), 
Master Read (subopcode 19), Read Call Block (subopcode 1A), Master Write 
(subopcode IB), and Redirect Assign LUNO (subopcode 1C) for interprocess com- 
munication (IPC). 

— SVC > 3D (Semaphore Operations) 

— SVO 40 (Segment Management) 
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— SVC > 41 (Initiate Event) 

— SVC > 42 (Wait for Event) 

— SVO 43 (Name Management) 

— SVO 45 (Get Encrypted Value) 

— SVC > 46 (Get Decrypted Value) 

— SVC > 47 (Log Accounting Entry) 

— SVC >48 (Job Management) 

— SVC > 49 (Get Accounting Information from TSB) 

— SVC >4A (Modify BTA or JCA Size) 

— SVC > 4C (Return Code Processor) 

— SVC >4F (Post Event) 

In DX10, a task can issue the following SVCs to affect any other task; in DNOS, these 
SVCs affect only tasks within the requesting task’s job: 

— SVC > 07 (Activate Suspended T ask) 

— SVC > OE (Activate Time-Delayed Task) 

— SVC > 2C (Read/Write TSB) 

— SVC > 2D (Read/Write Task) 

— SVC >33 (Kill Task) 

— SVC > 35 (Poll Status of Task) 

The following SVCs have options in DNOS that are not available in DX10. Each of these 
uses fields that are marked as reserved in DX10. If DX10 tasks using these SVCs have all 
reserved fields set to zero, no compatibility problems should occur, 

— SVO IF (Scheduled Bid Task) 

— SVC > 26 (Install Procedure Program Segment) 

— SVC >2B (Bid Task) 

— SVC >2E (Self Identification) 
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• In DNOS, SVC > OF (Abort I/O Requests by LUNO), has a different call block format and a 
different scope than in DX10. The SVC is vaiid oniy for priviieged tasks in DX10. Any task 
may issue the SVC for its own LUNOs in DNOS, 

• In DNOS, SVC > 3F (Retrieve System Data) has a different cail biock format than in DX10 
to provide access to the new data structures of DNOS. 

• In DX10, It was recommended that users identify messages passed using the intertask 
message queue by the task run ID of the task to receive the message. In DNOS, task run 
IDs are job-local rather than global. Thus, users of the Get Data (>1D) and Put Data 
(>1C) SVCs need to be aware of this difference. DNOS users should use IPC for this 
type of exchange and avoid SVCs > 1C and > 1 D. 

• In DX10, the table area reserved for the intertask message queue is specified during sys- 
tem generation. In DNOS, the size of the queue Is set to be a maximum of 2,000 bytes. 

• The following SVCs supported by early releases of DX10 are not supported by DNOS. In 
some cases, features of DNOS replace the functions of the SVCs no longer supported. 

— SVC > 00, subopcodes > 8x (not supported since DX10 2.2) 

— SVC > 05 (Bid Task; replaced by > 2B) 

— SVC > 08 (Unconditional Character Input) 

— SVC > 15 (Disk Utility; not supported since DX10 2.2) 

— SVC > 16 (End of Program; replaced by > 04) 

— SVC > 18 (Conditional Character Input) 

— SVC > 19 (Set Condition Bit; not supported since DX10 2.2) 

— SVC > 1 A (913 VDT Utility; not supported since DX10 2.2) 

— SVC > IE (Abort I/O by Call Block Address; not supported since DX10 3.2) 

— SVO 23 (Make Task Privileged) 

— SVC > 30 (Get Event Character) 

— SVC > 32 (Get System Table Address; not relevant to DNOS) 

— SVC > 39 (Get Event Character by LUNO) 

— SVC > 3A (Set Event Key; not supported in DX10) 

— SVC > 3C (Diagnostic Dump; not supported in DX10 systems) 
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• Some DNOS SVC processors return error codes that DX10 does not return. Some of the 
DX10 codes represent errors that cannot occur in DNOS; these codes have been 
assigned new meanings, if a program executes in both operating system environments 
and checks for a particuiar error code or for ail error codes, the program must be 
reviewed carefully to ensure it Is correctly checking for errors. A determined effort was 
made to retain identical codes in DX10 and DNOS for many common conditions. 

• The Read/Write Task SVC (>2D) processes requests to read or write to an odd-byte 
address boundary in DNOS. In DX10 the address is rounded down to the nearest even 
address. 


1 1 .7 USER-WRITTEN SYSTEM SOFTWARE 

Since the internal data structures of DNOS differ from those of DX10, any user-defined SVC pro- 
cessors that must be used with both systems and that access system data structures must have 
source code modifications. User-defined SVC processors that are independent of the operating 
system structures need minimal modifications from DX10 format to fit into the DNOS table-driven 
scheme of access. All user-defined SVC processors must be reassembled and included in system 
generation to be linked into DNOS. Section 4 describes requirements for user-defined SVCs. 

User-written DSRs that must be used with both DX10 and DNOS must be rewritten for DNOS to 
make use of new interfaces to the I/O subsystem and to conform to changes in data structures. 
Consult the DNOS System Design Document and the section of this manual concerning DSRs for 
further information. 

Other user-written system tasks that access system data structures and are used with both oper- 
ating systems must be modified for use in DNOS. See the DNOS System Design Document for 
details on system internals and how to write system tasks. 


11.8 SYSTEM CONSOLE 

DNOS allows a terminal to be designated as the system console. The user of that terminal 
becomes the system operator. DX10 has no parallel function in DX10. Some commands that have 
a global scope in DX10 have a job scope for DNOS users and a global scope for the DNOS system 
operator. 

To designate a terminal as system console and the user who is logged on at that terminal as sys- 
tem operator, dnter the Execute Operator Interface (XOI) command. 

The command fails if a system console designation is in effect for another terminal. If no terminal 
Is designated as system console, the terminal at which the command is entered becomes the sys- 
tem console and continues to be the system console until a Quit Operator Interface (QOI) com- 
mand is successfully executed at the system console. Refer to the DNOS System Command 
interpreter (SCi) Reference Manuai for further information about these commands and to the 
DNOS Operations Guide for general instructions on using the operator Interface. 
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A user must be designated system operator in order to perform the following functions: 

• Show status of any job in the system 

• Show status of all I/O in progress in the system 

• Force abnormal termination of any task in the system 

The system operator receives operator messages and requests untii pressing the CMD key to acti- 
vate SCI and enter other commands. Any messages are queued until the system operator again 
enters the XOI command. 

Operator messages are displayed following execution of each SCI command if the system opera- 
tor enters a Receive Operator Messages (ROM) command while SCI is active. The command is as 
follows; 

[] ROM 

RECEIVE OPERATOR MESSAGES 
MESSAGES: ALL 

The system operator should enter the XOI command again after entering the SCI commands (that 
is, when the terminal is idle). Otherwise, messages are not displayed. 

When an operator message contains a request ID followed by an asterisk, the system operator 
must respond. The task that issued the request is suspended pending receipt of the response. 
When the system operator has performed the requested function and the operator interface task 
is active, the operator presses the F4 key and enters the number of the request to which he is 
responding. If the system operator is unable to perform the request and the operator Interface 
task is active, the operator presses the F5 key, enters the number of the request, and indicates 
whether or not to terminate the request. The operator uses the Respond to Operator Interface 
Request (ROR) command and the KIM Operator Interface Request (KOR) command (which is 
described in the DNOS System Command Interpreter (SCI) Reference Manual) instead of the F4 
and F5 keys when SCI is active. 
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12.1 INTRODUCTION 

You can use a number of features in DNOS to alleviate problems that exist in the DX10 environ- 
ment. Many of these enhancements have no counterparts in DX10. The following paragraphs 
describe ways to utilize these DNOS features. Further detail is available in other DNOS manuals. 


12.2 DNOS JOB ARCHITECTURE 

DX10 users often require several background tasks to be active at the same time. As a DNOS user, 
you can activate batch jobs with the Execute Batch Job (XBJ) command. You can initiate any 
number of batch jobs at one time since each of these jobs is independent of any terminal and of 
any other job. However, during system generation, the systems programmer specifies the limit to 
the number of jobs that can be active at one time; the default value is 32. Any jobs initiated after 
this limit is reached are placed in a queue. When an active job terminates, a job from the queue 
becomes active. In addition to the active job limit, there is also a batch job limit. The systems pro- 
grammer can therefore govern not only how many jobs are active, but how many can run in batch 
mode at the same time. 

Several users may be logged on with the same ID in different jobs or the same job. When several 
users are logged on at different terminals, but in the same job, they can each have their own SCI 
task governing the interaction. In this situation, each user begins the interactive session with the 
set of synonyms and logical names currently saved on disk as the permanent copy for that user ID. 
When the last user quits, his current set of synonyms and logical names becomes the new 
permanent copy. Having several users in the same job requires less system table area for job 
structures than having each user run in his own job. 

A feature known as the keyboard bid is used when you log on to SCI. By pressing the attention key 
followed by the exclamation point, you bid a log-on task, which in turn bids SCI. You have control 
of the task that is bid for this sequence. During system configuration, you can provide a table of 
entries showing what task to bid for a given sequence of attention plus some other key. You can 
define the sequence to bid a task after bidding a log-on task, or you can define it to bid a task 
within a running job. For example, you might define your own task to implement the PRINT key or 
to replace SCI. Details about using this feature can be found in the I/O section of the DNOS Sys- 
tem Design Document. The SCI commands used with this feature are the Modify Command Defini- 
tion Table (MCDT), Show Command Definition Table (SCDT), and Modify Device Configuration 
(MDC) commands. These commands are described in the DNOS System Command Interpreter 
(SCI) Reference Manual. 
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12.3 LOGICAL NAMES 

Logical names provide several features in DNOS including concatenated files, multifile key 
indexed file (KIF) sets, and access to the spooler from user tasks. 

You can create a concatenated set of sequential files or a concatenated set of relative record files 
by using the Assign Logical Name (ALN) command. Subsequently, the concatenated set is a 
single file. Access to the logical name from the SCI command level or from the user task actually 
affects the appropriate physical file of the concatenated set. The files can reside on one or more 
volumes. 

You can also use the ALN command to create a multifile KIF set. By using a logical name, you can 
treat two or more KIFs having the same characteristics as one file. The files In use can reside on 
one or more volumes. When you execute the ALN command, all files specified after the first file 
must be empty. This feature can extend a KIF that nearly fills a volume or uses as much space as 
desired on a single volume. When the first file becomes full, a second is created on another vol- 
ume using the same characteristics as the first file. You then use the ALN command to specify a 
logical name associating the two files. 

You can also use logical names to customize user access to the spooler. Once you have made a 
device available to the spooler by using the Modify Spooler Device (MSD) command, users can 
direct output to that device by using the Print File (PF) command. You can also define your own 
logical names for particular spooler devices by using the ALN command. When you specify a 
spooler logical name, you can provide the default parameters for that name including such items 
as number of copies to print, whether or not to delete the file after printing, and the number of 
lines per page. You can also assign a global logical name to access spooler devices that are avail- 
able to all system users. 

Once a Spooler device has an assigned logical name, you can use that logical name in any SCI 
command that generates an output listing. For example, you might respond to the LISTING 
ACCESS NAME prompt for the Execute Macro Assembler (XMA) SCI command with OUTPUT, If 
OUTPUT is a logical name for LP01. You can also use the PF command with the selected logical 
name. In addition, you can specify the logical name as your output device or file name for output. 
In all cases, the Spooler queues the output file for printing at the device specified with the ALN 
command. 
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12.4 SCI FEATURES 

A number of SCI features are obvious to users of DX10; others are more subtle. The following list 
describes the less obvious features: 

• Error messages are of a uniform format and style for utilities supported on DNOS. 

• A synonym and logical name table is provided. Each table has as many as 12,000 bytes 
of space. 

• A fast VDT mode is available when the VDT terminal is identified as DEFAULT 
MODE = VDT in the Modify Terminal Status (MTS) command. This mode has severai 
advantages: 

— Menus are displayed quickly, using a singie operation. 

— Each screen of data displayed by the Show File (SF) command is written with a 
single operation. 

— Function keys F6 (line numbers), F3 (horizontal scroll left), F4 (horizontal scroll 
right). Next Field, and Previous Field are effective with the SF command. 

• Graphics characters can appear in menus. 

• The Enter key allows you to accept all of the current prompt responses to a command 
procedure shown on the screen. 

• The Erase Input key allows you to reset any initial values of the responses shown on the 
screen and return to the first command prompt shown on the screen. 


12.5 INTERPROCESS COMMUNICATION (IPC) 

DX10 tasks use several limited mechanisms to exchange information between tasks. These 
include access to the system common data area and use of the intertask message queue with the 
Get Data SVC (> 1 D) and Put Data SVC (> 1C). DNOS IPC provides a considerably more flexible tool 
for communication. IPC functions like an I/O resource, making use of the I/O SVC (>00) as the 
transmission mechanism. 

DNOS supports IPC flexibly from assembly language programs. The high-level languages and 
applications environment processors use IPC Internally. High-level languages can use symmetric 
channels for resource-independent I/O like any I/O device, making use of ASCII Read and ASCII 
Write operations. Use of master/slave channels, however, requires careful writing of the owner 
task by using SVCs. 
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12.6 PERFORMANCE MONITORING 

The following utilities are available with both DX10 and DNOS for monitoring performance. These 
include the following: 

• The memory map available from the Show Memory Map (SMM) command 

• The memory statistics from the Show Memory Status (SMS) command 

• The current set of tasks active (in a job) as shown by the Show Task Status (STS) 
command 

• The various terminal, LUNO, and output status lists 
In addition, DNOS provides the following monitoring utilities: 

• Current table use and activity levels for various DNOS subsystems from the Execute 
Performance Display (XPD) command 

• The current set of jobs (and, optionally, tasks in these jobs) from the Show Job Status 
(SJS) command and the List Jobs (LJ) command 

• A dynamic display of tasks in a given job from the Execute Job Monitor (XJM) command 


12.7 PERFORMANCE OPTIMIZATION 

You can use several features of DNOS to optimize the performance of the 990 minicomputer. The 
following features aid in extending the device capacity and execution performance of the 
computer: 

• Alternate ways to structure SCI sessions 

• Keyboard bid of application tasks 

• Types of LUNOs 

• Batch jobs 

• Miscellaneous items 
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1 2.7.1 Alternate Ways to Structure SCI Sessions 

DNOS is flexible in the way in which SCI sessions are structured and started. The following 
features are useful in structuring an SCI session for your specific needs. 

• SCI is available to users in their own jobs or in the same jobs as other users. 

• You can log on to SCI from one terminal and then, by using the Execute Task (XT) 
command, activate other terminals. 

• You can log on to SCI at one terminal and start a user task that bids tasks at other 
terminals. 

Each execution of SCI uses approximately 100 bytes of system table area. You might want to use 
less system table area for applications that do not require SCI. However, applications developed 
with DNOS need access to synonyms and logical names that are created in the SCI environment. 
To access these, you must start the job executing without SCI in an environment that is defined by 
using SCI. You have several options for providing that environment. 

You can use an SCI job to establish a set of synonyms and logical names and save these in a file . 
When you log on using that ID, those synonyms and logical names are available. Terminals modi- 
fied by the Modify Terminal Status (MTS) command can request name management files. By using 
the Snapshot Name Definitions (SND) command, you can save the names and parameters for the 
task that will be the application task to execute without SCI. You can then start the application 
task by using the keyboard bid. This allows applications that are written in high-level languages to 
execute without SCI. 

You can also use the SND command to save the required names for the application environment 
but not specify the parameters. A keyboard bid can then start an assembly language task that 
uses the S$BIDT routine from the SCI S$ routines to bid a task written in a high-level language and 
supply it with the required parameters. 

1 2.7.2 Keyboard Bidding of T asks 

A DNOS user can bid an application task by using a predefined keyboard sequence. A keyboard 
bid sequence can be defined as active for some terminals but inactive for others. Keyboard bids 
are especially useful in environments where SCI is used only to bid an initial program. Direct Initia- 
tion of the application would eliminate the need for SCI entirely and reduce the amount of system 
overhead. Keyboard bids are processed by a Device Service Routine (DSR). For more details on the 
internal processing, refer to the section entitled Writing a DSR. 


CAUTION 

DNOS currently has keyboard bid sequences defined. Texas Instru- 
ments reserves the right to add sequences during subsequent 
releases of DNOS. 
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Keyboard bidding makes use of the system directory .S$CDT. A file is created in this directory the 
first time an initial program load (IPL) takes place. The name of the file will be identical to the 
name of the kernel program file In use. This file contains a record for each device type. These 
records are known as Command Definition Tables (CDTs). One CDT pertains to 911s, another for 
931s and so on. Each CDT may contain up to 16 command definition entries (CDEs). If you want 
more than one terminal type to have keyboard bid access to a task, you will need to modify the 
CDT for each terminal type. 

A CDE contains the information needed to execute a keyboard bid from the associated device. 
The keyboard sequence you use must have the following format: Attention key followed by 
another keyboard character. The selected character is stored in the CDE, along with the task ID 
and global LUNO for the program file from which the task is to be bid. The CDE may also contain 
two words of task bid parameters. 

Several options are Indicated by a CDE. One may specify if the task is to be bid in the current job 
or in a new job. If the task is to be bid in a new job, a logon task is needed to create the job. The 
logon task ID and program file LUNO are stored in the CDE. If a logon task is used, an option 
allows the station number and/or the bid character as task bid parameters to be passed to the 
logon task. 

If the DNOS logon task is used to bid the application task, the even loading option is supported. 
With even loading, the task is bid in an existing job. The user ID of the job can be prompted for or 
specified in the CDE. All jobs running under the specified user ID are searched; the task is bid in 
the job containing the fewest tasks. 

The SCI commands provided to set up the command definition tables include the following: 

1. The Show Command Definition Table (SCDT) command allows you to examine the 
defined command definition entries for a given device in the command definition table. 

2. The Modify Command Definition Table (MCDT) command allows you to add or delete 
command definition entries to a command definition table. 

SCDT and MCDT are used to define keyboard sequences. The next step is to enable or disable 
sequences for specific terminals. 

During system generation, a CDE mask Is defined for each device. The bits in this mask corre- 
spond to an entry in the CDT associated with the device. For example, the CDT for a 931 might 
have the first four entries defined. Indicated by a mask of > FOOD. For a particular terminal, this 
mask may be changed by using the Modify Device Configuration (MDC) command. Each terminal 
which uses something other than the supplied default sequences must have its CDE mask 
changed. Changes made will take effect after the next IPL. 

Refer to the DNOS System Command Interpreter (SCI) Reference Manual for details concerning 
the SCDT, MCDT, and MDC commands. 
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12.7.3 Types of LUNOs 

When you assign global LUNOs to files, some structures are placed in the system table area. If 
you wish to minimize the use of system table area, avoid using global LUNOs. 

While structures for global LUNOs are placed in the system table area, structures for job-local and 
task-local LUNOs are placed in the user’s job communication area (JCA). These structures include 
the logical device table (LDT) and resource privilege block (RPB) for any assigned LUNO. An LOT is 
20 bytes long and an RPB is 18 bytes long. Other structures may also be in the JCA, if the LUNO is 
assigned to a file or IPC channel. 

If a job has several tasks and each of these tasks accesses many resources, the large number of 
associated LUNO structures may tax the JCA. In this case, you may wish to consider shared 
LUNOs. The shared LUNO capability of DNOS minimizes the number of such structures for the 
same resource for tasks in the same job. When a given task assigns a shared LUNO to some 
resource and opens that LUNO, other tasks in the same job can also use the same LUNO without 
an Assign operation. Rather than having multiple LDTs and RPBs (that is, one pair for each Open 
operation issued), you have one LDT and as many RPBs as Assign operations. 

More than one task at a time can open a shared LUNO, but only one task at a time can open a job- 
local LUNO. Each task that uses a shared LUNO must open that LUNO and is subject to the stand- 
ard cross checking with other Open operations. 

No LUNOs are assigned to the program file when tasks are bid from .S$UTIL or .S$SHARED with 
system-supplied commands. However, a LUNO is assigned when the .BID is from SCI, and that 
LUNO remains until the task that was bid terminates. 

12.7.4 Batch Jobs 

DNOS can process both batch jobs and interactive jobs. Use of the Execute Batch Job (XBJ) 
command allows you to execute batch streams independent of terminals, leaving those terminals 
free for other operations. 

12.7.5 Miscellaneous Items 

A Copy Directory (CD) command of the system disk to a clean disk eliminates fragmentation 
(secondary allocations). This aids in minimizing secondary allocation table (SAT) structures for 
any shared files with structures in the system table area. 

Since a six-byte structure is built in the system table area for each directory level of a file name, 
complex directory structures can use large amounts of the system table area. Consequently, 
when organizing a disk directory structure, you should use a minimum number of directory levels 
for files that you frequently access. However, you should use at least one directory level and avoid 
putting files directly under .VCATALOG. Any change to a file directly under .VCATALOG locks 
.VCATALOG during an update and slows system response. Also, your directory should be large 
enough so that it is never more than 90 percent full. The 10 percent unused space maximizes the 
hashing algorithm. 
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12.8 SYSTEM CONFIGURATION UTILITY 

Modifications to the system tabie sizes and supported devices of DX10 require use of the system 
generation utiiity. in DNOS, you can make changes to tabies, devices, and a number of other char- 
acteristics using an interactive utiiity whiie the system is running. The utiiity is accessed by the 
Execute System Configuration Utiiity (XSCU) command. Some of the changes are made whiie 
executing the utiiity. Others take effect when the system goes through its next iPL. 


12.9 S$SYSTEM DIRECTORY 

DNOS provides severai toois for both the systems programmer and Texas instruments fieid per- 
sonnei in the directory .S$SYSTEM on the DNOS system disk. This directory inciudes the fiie 
.S$SYSTEM.S$HSTRY and the command procedure directory .S$SYSTEM.S$$CMDS. 

The S$HSTRY fiie records information concerning the instaiiation of software products soid by 
Texas instruments, it is updated by the instaiiation batch streams for ianguages and appiications 
environment processors, by the Modify Voiume Information (MVI) command, and by the com- 
mands used to install a new version of DNOS. This history file Is interrogated by the List Software 
Configuration (LSC) command when producing a report of the current state of software on the 
system. 

The command procedure directory .S$$CMDS includes the procedures needed to build the history 
file. Users who develop large applications might be interested in maintaining history records 
about installation of those applications. It also includes the XPROCCVT command to aid in con- 
verting DX10 batch streams and command procedures for DNOS. Other members of the 
.S$SYSTEM.S$$CMDS directory are not intended for use by users. 


12.10 SYSTEM COMMAND PROCEDURES 


DNOS includes general system command procedures, which are described in the following para- 
graphs. 


12.10.1 Begin Update Documentation (BUD) 

When used in a batch stream, the BUD command starts an update documentation sequence that 
ends with an EUD (End Update Documentation) command. It sends a message to the history file 
(.S$SYSTEM.S$HSTRY) indicating that installation or patching of the specified software product 
has begun. When used interactively, BUD does both the update and end update operations. 

Prompts 

BEGIN UPDATE DOCUMENTATION 


VOLUME BEING UPDATED 
PACKAGE NAME 
RELEASE NUMBER 
RELEASE DATE 
SYSTEM COMPONENT NAME 
BEGIN NEW ENTRY? 


volume name 
character (s) 
character(s) 
character (s) 
character (s) 

CYES/NO] (YES) 
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Prompt Details 
VOLUME BEING UPDATED 

The disk volume for which the history information for this installation or patch batch stream 
is being executed. 

PACKAGE NAME 

From 1 to 33 characters specifying the product name or description. It may also be a part of a 
product, as in the case of products with pieces that are maintained or patched as a separate 
entity (for example, the kernel and utility portions of the DNOS operating system). 

RELEASE NUMBER 

From 1 to 7 characters representing the release level or revision level of the associated soft- 
ware product. 

RELEASE DATE 

The eight-character date entered In the format MM/DD/YY and associated with the release 
number. 

SYSTEM COMPONENT NAME 

From 1 to 11 characters specifying the keyword unique to each software product. This is 
essentially an abbreviation for the package name. Keywords beginning with DN and UT are 
reserved for the DNOS operating system. Other keywords are used by various products. 
Texas Instruments may modify or add to these keywords as new products become available 
without regard to conflict with any user’s use of this command. 

BEGIN NEW ENTRY? 

YES or NO. This prompt controls formatting of the history file (.S$SYSTEM.S$HSTRY). You 
should accept YES (the initial value) except for DNOS kernel patching. For kernel patching, 
enter NO. 


Examples 

BUD VOLUME BEING UPDATED=DS01 , 

PACKAGE NAME=DN0S OPERATING SYSTEM (KERNEL), 

RELEASE NUMBER = 1 .0.0, RELEASE DATE = 8/01 /81 , 

SYSTEM COMPONENT NAME=DP, BEGIN NEW ENTRY?=N0 

BUD VOLUME BEING UPDATED=DS01 , 

PACKAGE NAME=DN0S OPERATING SYSTEM (UTILITY), 

RELEASE NUMBER = 1 .0.0, RELEASE DATE = 8/01 /81 , 

SYSTEM COMPONENT N AME=UT . S$$UT I L , BEGIN NEW ENTRY?=YES 


Assumptions 

A subsequent EUD command will be executed. 
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Notes 

1. The command is located in an alternate command directory reserved for Texas Instru- 
ments commands. You must execute the primitive .USE.S$SYSTEM.S$$CMDS to 
access this command. 

2. The synonym $OT controls the target volume on which the .S$SYSTEM.S$HSTRY file 
resides. 

3. Since the BUD procedure is composed of SCI primitives only, it does not set the $$CC 
synonym and should not be followed by an EC command. If an error occurs in the BUD 
command, the batch stream In which it is used terminates. 

Related Commands 

EUD End Update Documentation 
LSC List Software Configuration 

12.10.2 End Update Documentation (EUD) 

The EUD command terminates an update documentation sequence that a BUD command began. 
It sends a message to the history file (.S$SYSTEM.S$HSTRY) indicating that installation or patch- 
ing has completed. It also indicates the number of the last patch applied. 

Prompts 

END UPDATE DOCUMENTATION 

LAST PATCH: [<integer>] 

RELEASE NUMBER: C c ha r a c t e r ( s ) ] 

Prompt Details 
LAST PATCH 

A user-defined integer value. This value allows you to monitor the last patch applied. For an 
installation batch stream, this field must be null in order to update the history file correctly. 

RELEASE NUMBER 

From 5 to 7 characters representing the release level or revision level of the associated soft- 
ware product. The format is v.r.e, where v represents the version of the product, r represents 
the revision level, and e represents the latest change. This format must be followed exactly 
for the List Software Configuration (LSC) command to work properly. 

Assumptions 

A prior BUD command Is executed. 
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Notes 

1. This command is valid only in batch streams and is Intended for use by Texas Instru- 
ments supplied software package installation and patch batch streams. The command 
is located in an alternate command directory reserved for Texas Instruments com- 
mands. You must execute the primitive .USE .S$SYSTEM.S$$CMDS to access this 
command. 

2. Since the EUD procedure is composed of SCI primitives only, It does not set the $$CC 
synonym and should not be followed by an EC command. If an error occurs in the EUD 
command, the batch stream in which It is used terminates. 

Related Commands 

BUD Begin Update Documentation 


12.11 MAINTAINING USER IDS 

If you attempt to copy a set of user IDs from one system disk to another, you must copy both the 
.S$USER directory and the .S$CLF file. If these two items are not from the same system version, 
various types of crashes and log-on problems can occur. Similarly, if you create a new system on 
an old system disk, you can preserve the old user IDs only if you preserve both the .S$USER direc- 
tory and the .S$CLF file. 

When changing from DNOS 1.1 to DNOS 1.2, the old user IDs cannot be used because of changes 
needed to support file security on DNOS. You must assign new user IDs for the DNOS 1 .2 system. 


12.12 SPOOLER SUBSYSTEM 

The spooler subsystem is the interface between users and output. It is designed to prevent 
unauthorized deletion or modification of output requests, yet give you complete control of 
requests that you initiate. The spooler subsystem consists of tasks that execute in the spooler job 
and tasks that execute in the user’s job. The spooler job is created by the initialization batch 
stream, .S$ISBTCH, which contains an Execute Job (XJ) SCI command. 

12.12.1 Spooler Directory 

The spooler directory, .S$SDTQUE, must reside on the system disk. This directory contains two 
types of files, a banner sheet file and spooler queue files. 
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12.12.1.1 Spooler Banner Sheet File. The banner sheet file, .S$SDTQUE.S$BANNER, specifies 
the format of the banner sheet that is displayed if you specify YES in response to the BANNER 
SHEET prompt in the Print File (PF) SCI command or in the S$SPLR routine. The standard banner 
sheet displays the user’s job name, the user ID, the pathname of the file being printed, the time, 
and the date. You can edit the banner sheet file to display customized banner sheets. The banner 
sheet file consists of various kinds of records that are 80 characters long. The following records 
are command records, which indicates that they are special display requirements: 


Command Records 


Description 


/JOB 

/USER 

/DATE 

/TEXT,CCCCCCCC 

/FILE 


Displays enlarged user’s job name 
Displays enlarged users ID 
Displays current date and time 
Displays enlarged characters CCCCCCCC 
Displays requested print file name 


If a record in the banner file is not a command record, the output device displays that record. By 
using the /TEXT command record and by editing the banner sheet file to contain specific display 
lines, you can create your own customized banner sheets. 


12.12.1.2 Spooler Queue File. The spooler queue file does not exist before the first initializa- 
tion of your DNOS system. The spooler automatically creates the file. The name of the spooler 
queue file is .S$SDTQUE.< name of the generated operating system> . Each operating system that 
is generated has a unique queue file. This avoids possible conflicts in hardware differences that 
each generated operating system supports. 

The spooler obtains the task bid parameters specified on the SCI Execute Job (XJ) command in 
the system initialization batch stream. These two Items, PARM1 and PARM2, allow each installa- 
tion to configure the spooler queue file to its particular needs. The structure of the queue file is 
described in the DNOS SCI and Utilities Design Document. 

The queue file contains a number of class name records. These records contain class name 
entries that are pseudo names associated with specified devices. The PARM1 parameter in the XJ 
command specifies the number of class name records that are to be included in the file when it is 
created. Each class name record can contain 48 class name entries; the class name table (CNT) 
template describes the class name record. 

The queue file contains a number of device table records. The device table records contain device 
entries. These entries contain information about each device available to the spooler or known to 
the spooler. The PARM2 parameter specifies the number of device table records that are to be 
included in the spooler queue file when It is created. Each device table record can contain 12 
device entries; the spooler device table (SDT) template describes the device table record. 

By editing the initialization batch stream .S$ISBTCH, you can structure the queue file for the par- 
ticular needs of your installation. For example, if one class name record is sufficient (that is, no 
more than 48 class names are required) but 30 spooler devices are required, specify the XJ PARM1 
/alue as 1 to obtain the 48 class names. To obtain three device table records, specify The XJ 
PARM2 value as 3. Each device table record contains 12 entries, which support a total of 36 
devices. 
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The first record of the queue file contains the name of the file, the version number of the operating 
system, the number of class name records, and the number of device table records. If the file 
exists already, the name in the file is compared to the name of the generated operating system. 
The version in the file is compared to the version of the operating system. The number of queue 
file class name records is compared to the value specified by PARM1, and the number of queue 
file device table records is compared to the value specified by PARM2. If any of these items do not 
correspond, the current file is deleted and recreated using the current parameters. 

Each record of the spooler queue file requires 768 bytes. The minimum size of the spooler queue 
file is four records, and the maximum size is 65,535 records. The file expands as it needs more 
space to continue operations. It is recommended that you regularly examine the size of the queue 
files In the .S$SDTQUE directory. You should delete old queue files that correspond to unused 
operating systems. If the current queue file is too large and is not needed, then you should follow 
the Spooler Clean-up routine described in paragraph that follows in this section. 

1 2.1 2.2 Spooler Device Attributes 

To change the attributes of a device that the spooler subsystem uses, use the Modify Spooler 
Device (MSD) SCI command. The DNOS System Command Interpreter (SCI) Reference Manual 
contains a complete description of the MSD command. 

12.12.3 Spooler Clean-up 

An unusual series of events can cause the spooler to stop functioning without allowing you to 
restart it in its current state. You must reinitialize the spooler environment by performing the 
following steps: 

1. Use the Show Output Status (SOS) command to see which files are waiting to be printed 
and to see the current devices available to the spooler and the class names assigned to 
each. Write down this information for later use. 

2. Using the operator console (issue an Execute Operator Interface (XOI) command if nec- 
essary) determine the ID of the spooler job by using a List Jobs (LJ) command on all 
jobs. 

3. Kill the spooler job by using the Kill Job (KJ) command. 

4. Delete the spooler queue file by using the Delete File (DF) command and specifying the 
logical name S$SDTQUE for the pathname. 


/ 
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5. Restart the spooler job by issuing an Execute Job (XJ) command. Specify the following 
responses: 

EXECUTE JOB 


SITE: 



JOB NAME: 

SPOOLER 


PROGRAM FILE PATHNAME: 

S$UTI L 


TASK ID OR NAME: 

04D 


PARM1 : 

1 (See previous 

discussion) 

PARM2: 

1 (See previous 

di scussion) 

STATION ID: 

OFF 


SYNONYM TABLE PATHNAME: 

.S$USER. SPOOLER 

.SYN 

PRIORITY: 

5 


JCA SIZE: 

MEDIUM 



6. Use the Modify Spooler Device (MSD) command and the list made In step 1 to reassign 
all devices and classes to the spooler. 

7. Execute the Print File (PF) command for each of the files that the SOS command 
showed as waiting to be printed. 

12.12.4 Spooler Temporary Files 

The names of the spooler temporary files are based on the job ID and task ID of the user whose file 
Is being printed. For example, the parameter xxxxxx of a spooler temporary file ID of .S$xxxxxx 
contains the job or task ID. If a temporary file remains after a system crash, you can delete it to 
save space. 
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Keycap Cross-Reference 


Generic keycap names that apply to all terminals are used for keys on keyboards throughout this 
manual. This appendix contains specific keyboard information to help you identify individual keys 
on any supported terminal. For instance, every terminal has an Attention key, but not all Attention 
keys look alike or have the same position on the keyboard. You can use the terminal information in 
this appendix to find the Attention key on any terminal. 

The terminals supported are the 931 VDT, 911 VDT, 915 VDT, 940 EVT, the Business System 
terminal, and hard-copy terminals (including teleprinter devices). The 820 KSR has been used as a 
typical hard-copy terminal. The 915 VDT keyboard information is the same as that for the 911 VDT 
except where noted in the tables. 

Appendix A contains three tables and keyboard drawings of the supported terminals. 

Table A-1 lists the generic keycap names alphabetically and provides illustrations of the 
corresponding keycaps on each of the currently supported keyboards. When you need to press 
two keys to obtain a function, both keys are shown in the table. For example, on the 940 EVT the 
Attention key function is activated by pressing and holding down the Shift key while pressing the 
key labeled PREV FORM NEXT. Table A-1 shows the generic keycap name as Attention, and a 
corresponding illustration shows a key labeled SHIFT above a key named PREV FORM NEXT. 

Function keys, such as FI, F2, and so on, are considered to be already generic and do not need 
further definition. However, a function key becomes generic when it does not appear on a certain 
keyboard but has an alternate key sequence. For that reason, the function keys are included in the 
table. 

Multiple key sequences and simultaneous keystrokes can also be described in generic keycap 
names that are applicable to all terminals. For example, you use a multiple key sequence and 
simultaneous keystrokes with the log-on function. You log on by pressing the Attention key, then 
holding down the Shift key while you press the exclamation (!) key. The same information in a table 
appears as Attentionl(Shift)!. 

Table A-2 shows some frequently used multiple key sequences. 

Table A-3 lists the generic names for 911 keycap designations used in previous manuals. You can 
use this table to translate existing documentation into generic keycap documentation. 

Figures A-1 through A-5 show diagrams of the 911 VDT, 915 VDT, 940 EVT, 931 VDT, and Business 
System terminal, respectively. Figure A-6 shows a diagram of the 820 KSR. 
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Table A-1. Generic Keycap Names 



The 820 KSR terminal has been used as a typical hard-copy terminal with the TPD Device Service 
Routine (DSR). Keys on other TPD devices may be missing or have different functions. 

'On a 915 VDT the Command Key has the label F9 and the Attention Key has the label F10. 
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Table A-1. Generic Keycap Names (Continued) 


Generic Name 


Erase Input 


Exit 


Forward Tab 


F1 


F2 


F3 


F4 


911 

VDT 


feRA$E: 

INPUT 


il 


TAB- 

SKIP 




FI 


F2 


m 


1 




940 

EVT 




M 




■ 


931 

VDT 


EBASEj 

INPUT: 




SHIFT O 


ESC I 


OH 

5 

n 

li*~ 

TAB 

. ^ '. M 



fi 

Ml 

IS 

B 


rP 

=n 

F2 






F3 


L 


a 


Business 

System 

Terminal 


r: 











M 


■ 


■ 


Notes: 

'The 820 KSR terminal has been used as a typical hard-copy terminal with the TPD Device Service 
Routine (DSR). Keys on other TPD devices may be missing or have different functions. 
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^ 


ESC 1 


^ 






r:=:^ 


Lisiy 








rF^ 

B i 

jnii 


i/mmm 




yiiiii 


1 ^, A 


D 
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T able A-1 . Generic Keycap Names (Continued) 


Generic Name 


F5 


F6 


F7 


F8 


F9 


F10 


911 

VDT 


940 

EVT 


931 

VDT 


Business 

System 

Terminal 


820’ 

KSR 






1 


kiiiigsiai 


B 


IL. 




rF=i 

E 


Fe 


w 



.F6 


m 


7 


F7 




iwmi 









^ ^ V 


FS ^ 

UBsmmrn 


m 




'^Pir 



w 






rizizTi 


F9 








H 








\jr :j.!° J. ^ 





'L. 



z 

ym^ 


j 


Notes: 

'The 820 KSR terminal has been used as a typical hard-copy terminal with the TPD Device Service 
Routine (DSR). Keys on other TPD devices may be missing or have different functions. 
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T able A-1 . Generic Keycap Names (Continued) 



’The 820 KSR terminal has been used as a typical hard-copy terminal with the TPD Device Service 
Routine (DSR). Keys on other TPD devices may be missing or have different functions. 
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Table A-1. Generic Keycap Names (Continued) 


Generic Name 

Insert 

Character 



Business 

System 

Terminal 


Next 

Character 




Next Field 






Notes: 

'The 820 KSR terminal has been used as a typical hard-copy terminal with the TPD Device Service 
Routine (DSR). Keys on other TPD devices may be missing or have different functions. 
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Table A-1. Generic Keycap Names (Continued) 


Generic Name 


911 

VDT 


940 

EVT 


931 

VDT 


Business 

System 

Terminal 


820 ' 

KSR 


Previous Line 








Ml 


Print 


3 





FI 

PRINT 






Repeat 




See 
Note 3 


See 
Note 3 


See 
Note 3 


Return 





Shift 



SHtFT O 






Skip 


^ 

Z/- 

TAB 

SKIP 

J 

Uf ^ 




7 


^ ;S 


iSKfP: 

/ .X-;-.. si 





Uppercase 

Lock 


CAPS 

tOCKI 


N 4 


m 


Notes: 

'The 820 KSR terminal has been used as a typical hard-copy terminal with the TPD Device Service 
Routine (DSR). Keys on other TPD devices may be missing or have different functions. 


’The keyboard is typamatic, and no repeat key is needed. 
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Table A-2. Frequently Used Key Sequences 


Function 

Key Sequence 

Log-on 

Attention/(Shift)! 

Hard-break 

Attention/(Control)x 

Hold 

Attention 

Resume 

Any key 


Table A-3. 

911 Keycap Name Equivalents 

911 Phrase 

Generic Name 

Blank gray 

Initialize Input 

Blank orange 

Attention 

Down arrow 

Next Line 

Escape 

Exit 

Left arrow 

Previous Character 

Right arrow 

Next Character 

Up arrow 

Previous Line 
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Figure A-1. 911 VDT Standard Keyboard Layout 
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FUNCTION 
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A- 




r 
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fcTaawBBBfcg 

fciMBaMwirs 

[SBJ 

[1311 

piQ|| 

IB3J 

pEBJ 

|S3I 

1^31 

11131 

I3S1 

1131 1 













O O O O 

IDLE EXEC TEST COMM 
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ERR MODE DS01 DS02 


HI 

M\ 



s 


Hi 

M 


IB2I 



CURSOR CONTROL 
AND EDIT KEYS v 

V 


NUMERIC 
KEY PAD 


DATA ENTRY 
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Figure A-3. 940 EVT Standard Keyboard Layout 
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Figure A-4. 931 VDT Standard Keyboard Layout 
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Figure A-6. 820 KSR Standard Keyboard Layout 






Alphabetical Index 
Introduction 


HOW TO USE INDEX 

The index, table of contents, list of illustrations, and list of tables are used in conjunction to ob- 
tain the location of the desired subject. Once the subject or topic has been located in the index, 
use the appropriate paragraph number, figure number, or table number to obtain the corre- 
sponding page number from the table of contents, list of illustrations, or list of tables. 

INDEX ENTRIES 

The following index lists key words and concepts from the subject material of the manual together 
with thearea(s) in the manual that supply major coverage of the listed concept. The numbers along 
the right side of the listing reference the following manual areas: 

• Sections — Reference to Sections of the manual appear as “Sections x” with the sym- 
bol X representing any numeric quantity. 

• Appendixes — Reference to Appendixes of the manual appear as “Appendix y” with the 
symbol y representing any capital letter. 

• Paragraphs — Reference to paragraphs of the manual appear as a series of 
alphanumeric or numeric characters punctuated with decimal points. Only the first 
character of the string may be a letter; all subsequent characters are numbers. The first 
character refers to the section or appendix of the manual in which the paragraph may be 
found. 

• Tables — References to tables in the manual are represented by the capital letter T 
followed immediately by another alphanumeric character (representing the section or 
appendix of the manual containing the table). The second character is followed by a 
dash (-) and a number. 

Tx-yy 

• Figures — References to figures in the manual are represented by the capital letter F 
followed immediately by another alphanumeric character (representing the section or 
appendix of the manual containing the figure). The second character is followed by a 
dash (-) and a number. 

Fx-yy 

• Other entries in the Index — References to other entries in the index preceded by the 
word “See” followed by the referenced entry. 
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Index 


\bort Entry Point 5.4.2.4 


Absolute Disk Address SeeADU 

Vccess Priviieges 2.1. 2.3 

Account Numbers 6.3.1 

\ccount Verification 6.3.1 

Accounting 

Data 6.2 

Fiies See.S$ACT1,S$ACT2Fiies 

Subsystem Impiementation 6.3 

Subsystem Requirements 6.3.2 

ACNM Field Prompt Type 3.4.4.1 

Active Job Limit 12.2 

Add 32-Bit Integers Routine 3.10.4.1 

ADR 2.3.1. 1,2.3.1.3 

ADU 2.2.4 

Alias Descriptor Record See ADR 

Alternate Termination Routine 3.10.1.15 

Arithmetic Utility Routines 3.10.4 

Arming Character 5.4.4 

ASCCHK Routine 5.5.7 

ASCCK2 Routine 5.5.7 

ASCII Codes, 

Special Language Characters T10-1 

Asynchronous: 

Data Structure: 

Allocation 5.6.4 

Linkages F5-13 

Device Support T5-2 

DSR: 

Building 5.8 

Design Overview 5.6.1 

Logic Flow F5-11 

Structure 5.6, F5-10 

Interrupt Processing Flow F5-12 

Multiplexer Interrupt Decoder 5.3.3.4 

Jatch: 

Job 1.5.1, 11.4 

Limit 12.2 

Stream 12.10.3 

Jegin Update Documentation 

Command Procedure 12.10.1 

iEMF Utility 9.2.1 

lid Task Routine 3.10.3, 5.5.3, 12.7.1 

lidding a Task 1.3.3 

lidding DSR Tasks 5.4.4 

lit Map 2.2.3.2 

ilank: 

Adjustment 2.1. 3.2 

Suppression 2.1. 3.2 

ilank-Suppressed: 

File 2.1. 1.1 

Record T2-12 

Hocked: 

File 2.1. 1.2 

Relative Record File 2.3.3.2 

Hocking 2.1.3.1 

Hocking Buffer 2.1. 3.1 


Branch Table Processor Routine 5.5.1 


BRB 5.3.2 

BRSTAT Routine 5.5.1 

BTA 1.1, 5.3.2 

BUD Command Procedure 12.10.1 

Buffer Table Area See BTA 

Buffered Request Block See BRB 

Build Expanded Message File 

Utility 9.2., 9.2.2 

Build Message File Utility 9.2.1 

Business System Terminal 

Keyboard Layout FA-5 

B-Tree 2.3.4.4, F2-15, F2-16 

CDE 5.4.4, 12.7.2 

CDR 2.3.1. 1,2.3.1.4 

CDT 5.4.4,12.7.2 

Channel 1.2, 1. 5.4.1 

Activity Master/Slave 1. 5.4.3 

Activity Symmetric 1. 5.4.3 

Characteristics 1. 5.4.3 

Creation 1. 5.4.2 

Descriptor Record See CDR 

Scope 1. 5.4.1 

CIC Command 1. 5.4.5 

Clock Interrupt Processor 1.3.10 

Close File Routine 3.10.2.5 

Collating Sequences 10.1 

Supported Languages T10-3 

Command: 

Definition Entry See CDE 

Definition Table See CDT 

Deletion 3.8.6 

Library, User 3.8.4 

Privilege Levels 3.5.1, T3-7 

Procedure 3.2.2, 3.8 

Design 3.8.1 

Installation 3.8.3 

Library, .S$CMDS 11.4 

SCI 12.11.3 

User-Defined 3.2 

Processor 3.2.3, 3.8 

Design 3.8.2 

Installation 3.8.3 

Interface Routines 3.9, 3.9.1 

Snapshot Name Definitions 12.7.1 

SND 12.7.1 

User-Defined 3.8.4 

Common Table Area 12.5 

Compare Strings Routine 3.10.3.3 

Concatenated: 

File 12.3 

Sets 1. 5.3.3 

Context Switch 1.1 

Controller: 

Error 8.1.1 

Interrupt Decoder HSR Subroutine . . 5.7.9 
Type Codes T5-5 


idex-2 
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Convert: 

ASCII to Binary Integer Routine . . 3.10.3.1 
Binary Integer to ASCII Routine .. 3.10.3.2 

Conversion Utilities 11.2 

Copy String Routine 3.10.3.4 

Country Code 10.2 

CPU Memory Requirements 11.2 

Crash Code 8.2.1. 1 

IPC Channel (CIC) Command 1.5.4.5 


Message Routine 3.10.1.13 

Operator Message 3.10.6.2 


CURMAP Address 8.2.1. 6 

Current: 

Jobs Set 12.6 

Table Use 12.6 


Data: 

Block 2.3.4.4, F2-17 

Buffer Address Field 11.3 

Format 6.2.2 

Structures 5.3.1 

Debugger Active Synonym 11.5 

DEFAULT Field Prompt Type 3.4.4.2 

Delayed Reentry Point 5.4.2.2 

Delete: 

IPC Channel (DIC) Command 1.5.4.5 

Protection 2.1. 2.1 

Deleting Commands 3.8.6 

Design Criteria 5.4.1 

Device: 

Information Block See DIB 


Interrupt Decoder 5.3.3 

I/O Operations 11.3 

Service Routine See DSR 


DIB 5.3.1, 5.4.1, 5.6.4 

DIC Command 1. 5.4.5 


Directory: 

File 2.1. 1.4, 2.3.1 

Characteristics 2.3.1. 1 

Dump F2-10 

Structure F2-4 

Overhead Record Format F2-5 

Structure . . . . F2-3 

Disk: 

Access Frequency 2.2.2 

File Structure 2.3 

Format Information T2-1 

Organization 2.2 

Physical Organization 2.2.3 

Space 2.1. 3.2 

Allocation 2.2.2 


Volume Information 2.2.3.1,F2-1 

Disk Fragmentation, Eliminating 12.7.5 

Divide 32-Bit Integers Routine 3.10.4.4 


DNOS: 

CPU Memory Requirements 11.2 

Environment 11.2 

Job Architecture 12.2 


Physical Layout FI-1 

SVCs 11.6 

Subsystems 1.5 

System: 

File Names T11-1 

Generation 11.4 

DSR 5.1, 5.4, 5.4.3 

See also Asynchronous DSR 

Debugging Techniques 5.9 

Design Overview, Asynchronous 5.6.1 

Entry Points 5.4.2 

Installation 5.8 

Link Control Stream 5.8 

Listing Example 5.10, F5-14 

Memory Map F5-8 

Structure F5-7 

Support Routines 5.5 

Task Activation 5.4.4 

Templates 5.3.1 

DSR/TSR Entry Points T5-1 

DX10 System File Names T11-1 

DXIO-to-DNOS .BID/.OVLY 

Converter 12.11.3 

Dynamic: 

Display of Tasks 12.6 

Modification of Run Time 

Parameters 1.3.8 

Priority Tasks 1.3.7 


ELEMENT Field Prompt Type 3.4.4.3 

Enable/Disable Status Change Notification 

HSR Subroutine 5.7.4 

End: 

Operator Interface Subsystem Interface 


Session 

Routine 3.10.6.4 

Update Documentation Command 

Procedure 12,10.2 

End-of-File See EOF 

ENDRCD Routine 5.5.2 

Entry Point: 

Abort 5.4.2.4 

Hardware Interrupt 5.4.2.1 

Initial Request 5.4.2,7 

Power-Up Initialization 5.4.2.3 

Priority Scheduler 5.4.2.6 

Time-Out 5.4.2.5 


Entry Points: 

DSR 5.4.2 

DSR/TSR T5-1 

EOF 2.1. 3.6 

EOR Processor Routine 5.5.2 


Error: 


Codes, Internal 9.2.1 


Interrupt 5.4.2.1 

Message Interface 9.4 

Reporting 9.1 

ERST AT Routine 5.5.2 

EUD Command Procedure 12.10.2 
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Exclusive: 

All Privilege 2.1. 2.3 

Write Privilege 2.1. 2.3 

Execute* 

Batch Job (XBJ) Command 1.5.1. 2 

Job (XJ) Command 1.5.1. 2 

Executing: 

Task 8.2. 1.2 

TaskJSB 8.2.1.3 

Workspace 8.2.1. 8 

Execution Priorities 1.3.7 

Expanded: 

Message Files 9.2.1 

Message File Utility 9.3.2 

Expanding Files 2. 1.3.5 

Expansion Chassis: 

Interrupt 5.3.3.3 

Interrupt Decoder F5-3 

Expert Mode 3.8.5 

Extended: 

Call Block Flag 11.3 

Operations SeeXOPs 

Extending SCI 3.2 


Failure Location 

Fast VDT Mode 

FDB 

FDR 

Field Prompt 

List 

Types 

File: 

Characteristics 

Concatenated 

Concatenation Restrictions 

Descriptor Block 

Descriptor Record 

Directory 

Characteristics 

Indicator 

I/O Operations 

Name 

Organization 

Protection 

Sharing 

Types 

Flag Word 

Flash Crash Routine 


8.2.1.4 

12.4 

1.4.3 

2.3.1. 1,2.3.1.2 

3.4.4 

3.5.1 

T3-4 

2.1.3 

12.3 

1. 5.3.3 

.... See FDB 

See FDR 

. 2.1. 1.4, 2.3.1 

2.3.1.1 

9.2.1 

11.3 

2.3.1. 1 

2.1 

2.1.2 

2.1.2 

2.1.1 

. 8.2.2. 1,F8-4 
8.1.2 


General Information Block F8-2 

Generic Keycap Names . . Appendix A, TA-1 
Get: 

Buffer Routine 5.5.9 

Event Character Routine 5.5.6 

Parameter Routine 3.10.1.3 

Queued Character Routine 5.5.5 

Synonym Value Routine 3.10.1.7 

TCA Routine 3.10.1.1 

Terminal Status Routine 3.10.1.5 

20-BitTILINE Address Routine 5.5.11 


GETC Routine 5.5.5 

GTADDR Routine 5.5.1 1 

Halt Job (HJ) Command 1.5.1. 2 

Hard Break Key Sequence 1 1 .2 

Hardware: 

Interrupt: 

Entry Point 5.4.2.1 

Processing F5-9 

Map Option 1.1.1 

Service Routine See HSR 

Trap 8.2.1. 9 

Hash Placement KIF 11.2 

HJ Command 1.5.1. 2 

HSR 5.6, 5.6.1, 5.6.4 

Baud Rate Codes T5-4 

Common Subroutines 5.7 

Object Modules T5-3 

Required Information 5.7 

Subroutine Classes 5.7 


Idle State 1.3.2 

Illegal Interrupt Routine 5.3.3.6, F5-6 

Image File 2.1. 1.4 

Immediate Write Option 2.1. 3.3 

Indicator Lights 8.1.1 

Information Interchange Codes 10.3 

Initial: 

Program Load See I PL 

Request Entry Point 5.4.2.7 

Initialization Problems, System 8.1 

initialize: 


Mailbox Interface Routine 3.10.7.1 

Operator Interface Routine 3.10.6.1 

System Data Base Routine 3.10.1.2 

Input Interrupt 5.4.2.1 


INT Field Prompt Type 3.4.4.4 

Interface: 

Routine Buffers 3.9.2 

Routines 3.10 

SCI 3.10.1 


Internal: 

Error Codes 9.2.1 

Interrupt Processor 1.3.11 

International: 

Data 10.2 

Languages 10.1 

Internationalizing Messages 10.5 

Interprocess Communication SeelPC 

Interrupt: 

Decoder: 

Asynchronous Multiplexer 5.3.3.4 

Device 5.3.3 

Expansion Chassis F5-3 

Multiple Devices F5-2 

Return Routine F5-5 

Routines 5.3.3 

Single Device F5-1 

Expansion Chassis 5.3.3.3 

Mask 5.4.2 
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Multiple-Device 5.3.3.2 

Processing F5-9 

Service Routine See ISR 

Single-Device 5.3.3.1 

Intertask Message Queue 11.6,12.5 

lOFCDT Routine 5.5.3 

lOGEC Routine 5.5.6 

lOGUB Routine 5.5.9 

lOMPIN Routine 5.5.10 

lOMPOT Routine 5.5.8 

IPC 1.5.4,12.5 

SCI Commands 1. 5.4.5 

Supervisor Calls 1. 5.4.4 

IPL 1.3.1, 1.4, 8.2 

IRB 5.3.2 

ISR 5.4.2.1, 5.6, 5.6.1, 5.6.2 

Functions 5.4.2.1 

I/O: 

Request Block See IRB 

Subsystem 5.3 

Japanese Character Codes T10-2 

JCA 1.1. 2.1 

JISCII T10-2 

Job: 

Architecture 11.2,12.2 

Control Capabilities 1.5.1.2 

Global Data 8.2.2.2 

initialization 6.2.1 

Management Request SVC ... 1. 5.1.1 

Status Block (JSB) 1.1. 2.1 

Structure 1.1. 2.1 

Temporaiy Files 1.5.3.2,11.2 

Termination 6.2.1 

Jobs 1.5.1 

JSB 1.1. 2.1, 8.2.2 

Executing Task 8.2.1.3 

List 8.2.2.2, F8-3 

KDR 2.3.1.1,2.3.1.5 

Kernel 1.1 

Key: 

Descriptor Record See KDR 

Sequences TA-2 

Keyboard: 

Bid 12.2,12.7.2 

Layout: 

Business System Terminal FA-5 

820 KSR FA-6 

911 VDT FA-1 

915 VDT FA-2 

931 VDT FA-4 

940 EVT FA-3 

Sequence, Predefined 12.7.2 

Status Block See KSB 

Keycap Name Equivalents, 911 VDT . . . TA-3 
Keycap Names, Generic . . Appendix A, TA-1 
Keyword List 3.3 


KIF 2.1. 1.3, 2.3.4 

Collating Sequence 10.4 

Disk Usage 2.3.4.6 

Hash Placement 11.2 

Keys 2.3.4. 1 

Logical Record 2.3.4.5 

Manager 10.4 

Multifile 12.3 

Sets 1. 5.3.3 

Records 2.3.4.2 

Sequential Placement 11.3 

Structure 2.3.4.4, F2-13 

Kill Job (KJ) Command 1.5.1. 2 

KJ Command 1.5.1. 2 

KSB 5.4.1 


Language: 

Line 3.3 

Processors 10.5 

Library, User Command 3.8.4 

Limit Registers 1.1.1 

Link Editor Control Stream 3.8.3 

Load,TILINE 8.1.1 

Loader: 

Flashing Crash Codes, System T8-2 

Phases, System T8-1 

Local Display File Routines 3.10.2 

Locking, Record 2.1. 2.2 

Logical: 

Address Space 1.1.1 

Name 3.1,3.4.2,12.3 

Names 1.5.3.1 

NameTable 3.1,11.3,12.4 

Records 2.1. 3.1 

Record Size 2.1. 3.1 

LP$1 Function 11.3 

LUNO: 

Types 12.7.3 

00 11.2,11.3 

Mailbox Subsystem 

Interface Routines 3.10.7 

Map 12.6 

File 1.1.1 

In Buffer Routine 5.5.10 

Option 1.1.1 

Out Current Buffer Routine 5.5.8 

Master/Slave: 

Channel 1. 5.4.3 

Owner Task 1. 5.4.3 

MB$INT Routine 3.10.7.1 

MB$RCV Routine 3.10.7.3 

MB$RLS Routine 3.10.7.4 

MB$SND Routine 3.10.7.2 

Memory: 

Mapping 1.1.1 

Resident User Tasks 1.1 

Statistics 12.6 
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Message: 

File Utilities 9.3.1, F9-1 

Processing Synonyms T3-3 

Migrating Between DXIOand DNOS ... 11.1 

Modify Job Priority Command 1.5.1. 2 

MJP Command 1.6.1.2 

Monitoring Utilities 12.6 

MultifileKIF 12.3 


Multiple-Device Interrupt 5.3.3.2 

Multiple Devices, Interrupt Decoder . . . F5-2 
Multiplexing Hidden Request Queue . . 5.4.5 

Multiply 32-Bit Integers Routine 3.10.4.3 

Multivolume File Sets 1. 5.3.3, 1. 5.3.4 


Name: 

Definition 3.4.3 

Stages 1. 5.3.5 

Management 1.5.3 

Name Manager, SVC 3.4.1 

Manager Task 3.1 

NAME Field Prompt Type 3.4.4.5 

Names, Reserved 9.2.1 

Nonreplicatable Tasks 11.2 

Nucleus 1.1 

OI$BGN Routine 3.10.6.1 

OI$COM Routine 3.10.6.2 

OI$END Routine 3.10.6.3 

OI$WAT Routine 3.10.6.2 

Open: 

File Routine 3.10.2.1 

File Specifying User ID Routine . . 3.10.2.2 

Operation 11.3 

Operator Interface Routines 3.10.6 

Output a Character HSR Subroutine . . . 5.7.5 
Output Interrupt 5.4.2.1 


Partial Bit Map 

PDT 

Special Extension 
Performance: 

Monitoring 

Optimization 

PF Command 

Physical: 

Device Table 


1.1,2.2.3.2, T2-2 
. . . . 5.3.1, 5.4.1 
5.8 

12.6 

12.7 

11.4 

See PDT 


Record Length 

Records 

Power-Up initialization: 

HSR Subroutine 

Entry Point 

Primary KIF Key 

Primitives 

Print File Command 

Priority Scheduler Entry Point 

Procedure Library 

Program: 

File 

Image Loader 

Errors 


2.1.3.1 

2.1.3.1 

. . 5.7.1 
. . 5.2.3 

5.4.2.3 
... 3.5 
. . 11.4 
5.4.2.6 
. . 3.2.2 

2.1. 1.4 
. . 1.4.2 
. . 8 . 1.2 


Put TCA Routine 3.10.1.11 

PUTCBF Routine 5.5.4 

PUTEBF Routine 5.5.4 


Queue 1.1. 2.3 

Character Routine 5.5.4 

Event Character Routine 5.5.4 

Servers 1.1. 2.3 

Structure FI -4 


RANGE Field Prompt Type 3.4.4.6 

RDB T4-1 


R03cI * 

HSR Subroutine 5.7.3 

Only Privilege 2.1. 2.3 

Input Signal or Function Operational 
Parameters and Information 

HSR Subroutine 5.7.7 

Receive Mail Routine 3.10.7.3 

Record: 

Blocking 2.1. 3.1 

Locking 2.1. 2.2 

Logical 2.1. 3.1 

Physical 2.1. 3.1 

Reentry Point, Delayed 5.4.2.2 

Relative Record: 


File 2.1.1.2,2.3.3,12.3.7 

File, Blocked 2.3.3.2 

File, Unblocked 2.3.3.1 

Release: 


Mailbox Routine 3.10.7.4 

TCA Routine 3.10.1.11 


Report TILINE Error Routine 5.5.13 

Request: 

Descriptor Block See RDB 

Flow 5.3.2 

Information Block See RIB 

Operation Code 5.3.2 

Time Interval Notification 

HSR Subroutine 5.7.8 

Reserved Names 9.2.1 

Resume Job (RJ) Command 1.5.1. 2 

Return Routine 5.3.3.5 

Return Time and Date Routine 3.10.1.10 

RE-ENTER-ME Routine 5.4.2.2 

RJ Command 1.5.1. 2 

ROM Loader 1.4.1 

Errors 8.1.1 

Run-Time Routines 11.5 


SAT Structures 12.7.5 

SCI 3.1 

Access to Logical Names 

and Synonyms F3-2 

Batch Mode 3.1 

Command 3.3 

Procedures 11.5,12.11.3 

Features 12.4 

Interactive Mode 3.1 


Interface Routines 3.10.1, 11.5 
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Language; 

Syntax 

Maintained Synonyms . . . , 

Modes of Operation 

Primitive 

Batch Stream 

Error Processing 

Primitives 

Run-Time Routines 

Sessions, Structuring . . . . 

Speciai Characters 

Task 

User Interface 

Variables 

SCS Command 

Search Name Correspondence 

Table Routine 

Secondary Allocation 

Table Structures 

Security Option Initialization . 

Segment Management 

Send Mail Routine 

Sequential: 

File 

Files 

Placement KIF 

Record Placement 

Set: 


3.3 

T3-2 

F3-1 

3.2.1,3.3,11.5 

3.6 

3.7 

3.5, T3-5, T3-6 

11.5 

12.7.1 

T3-1 

11.5 

11.4 

3.4 

1. 5.4.5 

3.10.1.8 

12.7.5 

1.4 

1.5.2 

3.10.7.2 

2.3.2 

2.1.1.1 

11.3 

. 2.3.4.4, F2-14 


Channel Speed HSR Subroutine . . . 5.7.6.1 
Data Character Format 


HSR Subroutine 

Device Parameters Suboperation 

Synonym Value Routine 

Shared Privilege 

Show: 

Channel Status (SCS) Command 
Job Status (SJS) Command . . . . . 

Single-Device Interrupt 

Single Device, Interrupt Decoder . . 

SJS Command 

Snapshot Name Definitions 

Command 

SND Command 


. . 5.7.6.2 
. . . 5.4.4 
. 3.10.1.6 
. . 2.1. 2.3 

. . 1. 5.4.5 
. . 1.5.1. 2 
. . 5.3.3.1 
. . . . F5-1 
. . 1.5.1. 2 

, . . 12.7.1 
. . 12.7.1 


Special: 

Langu^e Characters . . 
Usage Hie Protection . 

Usage Files 

Workspaces 

Split List Into Components 

Routine 

Spooler 

Banner Sheet File 

Clean-Up 

Device Attributes 

Directory 

Interface Routine 

Job 

Queue File 

Temporary Files 


10.1,T10-1 
... 2.1. 2.4 
... 2.1.1.4 
. . 8 . 2 . 1.10 

.. 3.10.1.9 
12.3,12.12 
. 12 . 12 . 1.1 
. . . 12.12.3 
. .. 12 . 12.2 
. . . 12 . 12.1 
. . . . 3.10.5 
.... 12.12 
. 12 . 12 . 1.2 
. .. 12.12.4 


Static Priority Tasks 1.3.7 

Station Local LUNOs 11.3 

Status: 

Interrupt 5.4.2.1 

Register 8.2.1. 5 

STRING Field Prompt Type 3.4.4.7 

String Utility Routines 3.10.3 


Routines 

Subtract 32-Bit Integers Routine . . . 3.10.4.2 

SVC Processor 4.1, 4.2, 4.3 

SVC Call Block 4.2.1 

SVC Definition Tables 4.2.2 

SVC Sysgen Requirements 4.2.4 

SVCs, Dirferences Under DNOS 11.6 

Symmetric Channel 1. 5.4.3 

Synonym 3.1 

Evaluation 3.4.1 

Name Table 12.4 

Table 3.1,11.4 

Synonyms 3.4.1 

System: 

Command Interpreter See SCI 

Command Procedures 12.10 

Components 1.1 

Configuration Utility 12.8 

Crash 8.1.1 

Dumps 8.2.3 

Forcing 8.2.4 

Problems 8.2 

Routine 1.3.12 

Disk 1.1. 2.4 

File Names 11.2, T1 1-1 

Files 1.1. 2.4 

Flow 1.3 

Initialization Problems 8.1 

Interrupt Decoder Routines 5.3.3 

Loader 1.4.3 

Error F8-1 

Flashing Crash Codes T8-2 

Phases T8-1 

Loaders 1.4 

Log Device 1 1 .2 

Memory Mapping 1.1.1 

Patch Area 8.2.1. 7 

Restart Task 1.4 

Structure 1.1 

Tables 1.1 

Table Sizes 12.9 

Tasks 1.1 

^^Flles 1.1. 2.4 

Interface Routines 3.1 

Routines 3.9, 11.5 

S$BIDT Routine 3.10.1.3,5.5.3,12.7.1 

S$CLOS Routine 3.10.2.5 

S$CMSG Routine 3.10.1.13 

S$CRASHFile 11.2 

S$GTCA Routine 3.10.1.1 
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S$IADD Routine . 
S$IASC Routine . 
S$IDIV Routine . . 
S$IMUL Routine . 
S$INT Routine . . 
S$ISUB Routine . 
S$MAPS Routine 
S$NEW Routine . 
S$OPEN Routine 

Error 

S$OPNS Routine 
S$PARM Routine 
S$PTCA Routine . 
S$RTCA Routine 
S$SCOM Routine 
S$SCPY Routine . 
S$SETS Routine . 
S$SNCT Routine 
S$SPLR Routine 
S$SPLT Routine . 
S$STAT Routine . 
S$STOP Routine . 
S$TAD Routine . . 
S$TERM Routine 
S$WEOL Routine 
S$WRIT Routine . 


. 3.10.4.1 
. 3.10.3.2 
. 3.10.4.4 
. 3.10.4.3 
. 3.10.3.1 
. 3.10.4.2 
. 3,10.1.7 
. 3.10.1.2 
. 3.10.2.1 
. . . . 11.5 
. 3.10.2.2 
. 3.10.1.4 

3.10.1.11 

3.10.1.12 
. 3.10.3.3 
. 3.10.3.4 
. 3.10.1.6 
. 3.10.1.8 
. . . 3.10.5 
. 3.10.1.9 
. 3.10.1.5 
3.10.1.15 
3.10.1.10 
3.10.1.14 
. 3.10.2.4 
. 3.10.2.3 


Table Overflow, Preventing 3.8.1 

Task: 

Activation 1.3.3 

Bidding a 1.3.3 

Characteristics 8.2.2.1 

Flag 8.2.2.1 

JSB, Executing 8.2.1. 3 

Priority 1.3.7 

Run IDs 11.6 

Scheduler - 1.3.4 

States 8.2.2, 8.2.2.1, F8-3 

Status Block (TSB) 1.1. 2.2 

Structure 1.1. 2.2, FI-3 

Termination 1.3.9, 6.2.1 

Temporary Files 2.1. 3.4 

Terminal: 

Local File See TLF 

Service Routine SeeTSR 

Terminate and Return to SCI 

Routine 3.10.1.13 

Termination, Task 1.3.9 

Text Editor Active Synonym 11.5 

TILERR Routine 5.5.13 

TILINE: 

Load 8.1.1 

Logical Address Space 1.1.1 

Peripheral Control Space See TPCS 

Time Slicing 1.3.5 

Time-Out Entry Point 5.4.2.5 

Timing Interrupt 5.4.2.1 

TLF 3.1 

TPCS 1.1.1 

Status 8.1.1 


Transfer: 


PDT Information to Task Memory 


Routine . . 
Vectors . . . . 
Trap, Hardware 

TSB 

TSR 


5.5.12 
. . . 1.1 
8.2.1. 9 
1.1. 2.2 


5.6, 5.6.1, 5.6.2 


Unblocked: 

File 2.1. 1.2 

Relative Record File 2.3.3.1 

Undetected Write Error, Preventing . . 2.1. 3.3 

Unit Select Error 8.1.1 

Unsolicited Interrupt 5.4.2.1 

User Command Library 3.8.4 

User Flags Byte 11.3 

UserlDs 11.2, 11.5, 12.11 

User-Defined: 

Commands 3.8.4 

DSRs 11.7 

SVC Processors 11.7 

System Software 11.7 

Wait for Operator Response 

Routine 3.10.6.3 

Write: 

EOL to File Routine 3.10.2.4 

Operational Parameters HSR 

Subroutine 5.7.6 

Output Signal or Function HSR 

Subroutine 5.7.2 

Protection 2.1. 2.1 

To File Routine 3.10.2.3 


XANAL 8.2 

Commands T8-3 

Listing 8.2.1 

XBJ Command 1.5.1. 2 

XFERM Routine 5.5.12 

XJ Command 1.5.1. 2 

XOP: 

Processing 1.3.6 

Vectors 8.2. 1.9 

XOPs 1.1 

XPROCCVT Converter 12.11.3 

YESNO Field Prompt Type 3.4.4.8 

$$CC Synonym 11.5 

$$DA Synonym 11.5 

$$EA Synonym 11.5 

.BID Primitive 3.5.9 

.DATA Primitive 3.5.13 

.DBID Primitive 3.5.10 

.ELSE Primitive 3.5.2 

.ENDIF Primitive 3.5.2 

.EOD Primitive 3.5.13 

.EOP Primitive 3.5.1 

.EVAL Primitive 3.5.6 
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.EXIT Primitive 3.6.5 

.IF Primitive 3.5.2 

.LOOP Primitive 3.5.7 

.MENU Primitive 3.5.17 


.MESSAGES.TEXT Directory 9.2.1,10.5 

.OPTiON Primitive 3.5.16 

Use With Internationai ASCII 10.4 

.PROC Primitive 3.5.1 

.PROMPT Primitive 3.5.3 

.QBID Primitive 3.5.11 

.RBID Primitive 3.5.12 

.REPEAT Primitive 3.5.7 

.SCI990 Library 3.9.1 

.SHOW Primitive 3.5.18 

.SPLIT Primitive 3.5.8 

.STOP Primitive 3.5.14 

.SVC Primitive 3.5.19 

Disai lowed SVCs with T3-8 

.SYN Primitive 3.5.4 

.S$ACCCHN Channei 1.2 

.S$ACT1,.S$ACT2Fiies 1.1. 2.4, 6.1 

.S$CDT Directory 1.1. 2.4 

.S$CDTQUE Directory 1. 1.2.4 

.S$CLFFile 1.1. 2.4 


.S$CMDS: 

Command Procedure Library 11.4 

Directory 1.1.2.4,12.9 

.S$CRASH File 1.1. 2.4 

.S$DIAG File 1.1. 2.4 

.S$DSTCHN Channel 1.2 

.S$EXPMSG Directory 1.1. 2.4 

.S$IPLFiie 1.1. 2.4, 1.4.3 

.S$ISBTCH File 1.1.2.4,1.4 

.S$ISLISTFile 1.1.2.4 

.S$LANGFile 1.1. 2.4 

.S$LOG1 File 1.1. 2.4 


.S$LOG1,.S$LOG2 Files 1.1.2.4 

.S$MAIL Channel 1.2 

.S$MSG Directory 1.1. 2.4, 9.2 

.S$MVI File 1.1. 2.4 

.S$OPER Channel 1.2 

.S$PWCSFile 1.1. 2.4 

.S$ROLLA, .S$ROLLD Files 1.1. 2.4 

.S$SCAFile 1.1. 2.4 

.SSSDTQUE Directory 12.12.1 

.S$SDTQUE.S$BANNERFile 12.12.1.1 

.S$SECURE File 1.1. 2.4 

.S$SGU$ Directory 1.1. 2.4 

.S$SHAREFile 1. 1.2.4 

.S$SHARED File 1.1. 2.4 

.S$SPOOL Channel 1.2 

.S$SYSLIB Directory 1. 1.2.4 

.S$SYSTEM Directory 1.1 .2.4, 1 2.9 

.S$SYSTEM.S$HSTRY File 12.9 

.S$USER Directory 1.1. 2.4 

.S$UTILFile 1.1. 2.4 

.S$XBJ Channel 1.2 

.S$UTIL 6.3.3 

.UNTIL Primitive 3.5.7 

.USE Primitive 3.5.15 

.WHILE Primitive 3.5.7 

7- Bit Character Check Routine 5.5.7 

8- Bit Character Check Routine 5.5.7 

820 KSR Keyboard Layout FA-6 

911 VDT: 

Keyboard Layout FA-1 

Keycap Name Equivalents TA-3 

915 VDT Keyboard Layout FA-2 

931 VDT Keyboard Layout FA-4 

940 EVT Keyboard Layout FA-3 
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USER’S RESPONSE SHEET 



Manual Date: March 1985 

User’s Name: 

Company: 
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City/State/Zip Code: 

Please list any discrepancy found in this manual by page, paragraph, figure, or table number in the 
following space. If there are any other suggestions that you wish to make, feel free to include 
them. Thank you. 

Location in Manual Comment/Suggestion 
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